cadabby 0.3.0__tar.gz

cadabby-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cadabby Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cadabby-0.3.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: cadabby
+Version: 0.3.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/bookian/cadabby#readme
+Project-URL: Issues, https://github.com/bookian/cadabby/issues
+Project-URL: Source, https://github.com/bookian/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.
+- **Multi-Domain Cognitive Architecture**: Partition knowledge into independent cognitive domains (e.g., `customers/`, `projects/`, `wiki/`) governed by localized `AGENTS.md` manifests and schemas.
+- **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).
+- **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), 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.
+
+### Contributing
+
+Working on Cadabby itself:
+
+```bash
+git clone https://github.com/your-org/cadabby.git
+cd cadabby
+uv sync                    # or: pip install -e .
+uv run python -m unittest discover -s 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 catalog auto-generated by cadabby
+├── log.md                # Append-only activity ledger
+│
+├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
+│
+├── wiki/                 # Canonical knowledge domain (5 typed subdirectories)
+│   ├── entities/         # Concrete objects, tools, datasets, libraries
+│   ├── concepts/         # Abstract ideas, algorithms, techniques
+│   ├── syntheses/        # Cross-domain integrations and summaries
+│   ├── comparisons/      # Trade-off evaluations (e.g. SQLite-vs-DuckDB)
+│   └── guides/           # Actionable procedures and runbooks
+│
+├── customers/            # (Optional) Custom cognitive domain
+│   ├── AGENTS.md         # Domain constitution & schema rules
+│   └── acme-corp/        # Flexible, unconstrained subdirectory layout
+│
+├── .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/concepts/Flash-Attention.md` citing `raw/attention-paper.pdf`.
+   - Add `[[wikilinks]]` to existing notes.
+   - Call `vault_verify_note` stamping the note with `agent:claude-code`.
+   *(Catalog `index.md` and activity `log.md` 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_lint`, verifies cache health, and tracks verification debt.
+
+### Workflow C: Human Reading & Editing (Obsidian & CLI)
+
+1. Open `my-vault/` in **Obsidian**:
+   - Wikilinks `[[Note-Stem]]` resolve automatically across subdirectories.
+   - `index.md` acts as your curated table of contents.
+2. **Review and certify notes**:
+   When a human inspects a note and certifies its accuracy:
+   ```bash
+   cadabby verify wiki/concepts/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 strictly enforced 5-type directory structures, you can partition knowledge into independent **Cognitive Domains** simply by creating top-level directories (e.g. `customers/`, `projects/`, `research/`, `team/`).
+
+### 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
+searchable: true
+schema:
+  allowed_types:
+    - account
+    - stakeholder
+    - interaction
+  require_sources: false
+  enforce_layout: 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. |
+| `searchable` | bool | `true` | Whether notes in this domain are indexed and returned in `vault_search`. |
+| `schema.allowed_types` | list[str] | `null` (unrestricted) | Allowed `type:` values in frontmatter. Violations trigger `ENUM_INVALID` in `cadabby lint`. |
+| `schema.require_sources`| bool | `false` | When `true`, notes in this domain must specify non-empty `sources: [...]`. |
+| `schema.enforce_layout` | bool | `false` | When `true`, notes must live in a subfolder matching their `type` (like in `wiki/`). When `false`, arbitrary directory nesting is permitted. |
+
+### Permissive vs. Strict Domains
+- **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.
+
+### 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`** | Epistemic health snapshot: tier counts, domain breakdown, verification debt, and unprocessed `raw/` files. |
+| **`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_verify_note`** | Cryptographically binds an `agent:<client_id>` attestation to the body SHA-256 (refuses `human:*`). |
+| **`vault_lint`** | Runs the six normative epistemic lint gates and returns typed diagnostics for self-healing. |
+
+### 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 | `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/concepts/Attention` |
+| `cadabby scaffold` | Scaffold a new typed note in any domain | `cadabby scaffold "Transformer" --type concept --domain wiki --desc "Attention model"` |
+| `cadabby update` | Patch frontmatter or append/replace sections | `cadabby update wiki/concepts/Transformer --replace-section "Overview:New text"` |
+| `cadabby verify` | Stamp cryptographic attestation on note | `cadabby verify wiki/concepts/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 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
+
+```bash
+# Run all unit and integration tests (105 tests):
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+All 12 falsifiable acceptance criteria from §10 are validated in `tests/test_acceptance.py`.
+

cadabby-0.3.0/README.md

@@ -0,0 +1,274 @@
+# 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.
+- **Multi-Domain Cognitive Architecture**: Partition knowledge into independent cognitive domains (e.g., `customers/`, `projects/`, `wiki/`) governed by localized `AGENTS.md` manifests and schemas.
+- **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).
+- **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), 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.
+
+### Contributing
+
+Working on Cadabby itself:
+
+```bash
+git clone https://github.com/your-org/cadabby.git
+cd cadabby
+uv sync                    # or: pip install -e .
+uv run python -m unittest discover -s 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 catalog auto-generated by cadabby
+├── log.md                # Append-only activity ledger
+│
+├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
+│
+├── wiki/                 # Canonical knowledge domain (5 typed subdirectories)
+│   ├── entities/         # Concrete objects, tools, datasets, libraries
+│   ├── concepts/         # Abstract ideas, algorithms, techniques
+│   ├── syntheses/        # Cross-domain integrations and summaries
+│   ├── comparisons/      # Trade-off evaluations (e.g. SQLite-vs-DuckDB)
+│   └── guides/           # Actionable procedures and runbooks
+│
+├── customers/            # (Optional) Custom cognitive domain
+│   ├── AGENTS.md         # Domain constitution & schema rules
+│   └── acme-corp/        # Flexible, unconstrained subdirectory layout
+│
+├── .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/concepts/Flash-Attention.md` citing `raw/attention-paper.pdf`.
+   - Add `[[wikilinks]]` to existing notes.
+   - Call `vault_verify_note` stamping the note with `agent:claude-code`.
+   *(Catalog `index.md` and activity `log.md` 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_lint`, verifies cache health, and tracks verification debt.
+
+### Workflow C: Human Reading & Editing (Obsidian & CLI)
+
+1. Open `my-vault/` in **Obsidian**:
+   - Wikilinks `[[Note-Stem]]` resolve automatically across subdirectories.
+   - `index.md` acts as your curated table of contents.
+2. **Review and certify notes**:
+   When a human inspects a note and certifies its accuracy:
+   ```bash
+   cadabby verify wiki/concepts/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 strictly enforced 5-type directory structures, you can partition knowledge into independent **Cognitive Domains** simply by creating top-level directories (e.g. `customers/`, `projects/`, `research/`, `team/`).
+
+### 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
+searchable: true
+schema:
+  allowed_types:
+    - account
+    - stakeholder
+    - interaction
+  require_sources: false
+  enforce_layout: 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. |
+| `searchable` | bool | `true` | Whether notes in this domain are indexed and returned in `vault_search`. |
+| `schema.allowed_types` | list[str] | `null` (unrestricted) | Allowed `type:` values in frontmatter. Violations trigger `ENUM_INVALID` in `cadabby lint`. |
+| `schema.require_sources`| bool | `false` | When `true`, notes in this domain must specify non-empty `sources: [...]`. |
+| `schema.enforce_layout` | bool | `false` | When `true`, notes must live in a subfolder matching their `type` (like in `wiki/`). When `false`, arbitrary directory nesting is permitted. |
+
+### Permissive vs. Strict Domains
+- **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.
+
+### 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`** | Epistemic health snapshot: tier counts, domain breakdown, verification debt, and unprocessed `raw/` files. |
+| **`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_verify_note`** | Cryptographically binds an `agent:<client_id>` attestation to the body SHA-256 (refuses `human:*`). |
+| **`vault_lint`** | Runs the six normative epistemic lint gates and returns typed diagnostics for self-healing. |
+
+### 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 | `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/concepts/Attention` |
+| `cadabby scaffold` | Scaffold a new typed note in any domain | `cadabby scaffold "Transformer" --type concept --domain wiki --desc "Attention model"` |
+| `cadabby update` | Patch frontmatter or append/replace sections | `cadabby update wiki/concepts/Transformer --replace-section "Overview:New text"` |
+| `cadabby verify` | Stamp cryptographic attestation on note | `cadabby verify wiki/concepts/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 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
+
+```bash
+# Run all unit and integration tests (105 tests):
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+All 12 falsifiable acceptance criteria from §10 are validated in `tests/test_acceptance.py`.

cadabby-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "cadabby"
+version = "0.3.0"
+description = "Zero-dependency engine for Karpathy-style LLM Wiki vaults with OKF trust tiers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Cadabby Contributors"}
+]
+keywords = ["llm-wiki", "knowledge-base", "mcp", "okf", "obsidian", "sqlite"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Database",
+]
+dependencies = []
+
+[project.scripts]
+cadabby = "cadabby.cli:main"
+
+[project.urls]
+Documentation = "https://github.com/bookian/cadabby#readme"
+Issues = "https://github.com/bookian/cadabby/issues"
+Source = "https://github.com/bookian/cadabby"

cadabby-0.3.0/src/cadabby/__init__.py

@@ -0,0 +1,3 @@
+"""Cadabby: Zero-dependency engine for Karpathy-style LLM Wiki vaults with OKF trust tiers."""
+
+__version__ = "0.3.0"

cadabby-0.3.0/src/cadabby/__main__.py

@@ -0,0 +1,8 @@
+"""Package entry point for python -m cadabby."""
+
+from __future__ import annotations
+
+from cadabby.cli import main
+
+if __name__ == "__main__":
+    main()

cadabby-0.3.0/src/cadabby/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Adapters implementing Cadabby driven and driving ports."""
+
+from cadabby.adapters.disk_storage import DiskNoteStorage, FileLedger
+from cadabby.adapters.memory_storage import InMemoryLedger, InMemoryNoteStorage
+
+__all__ = [
+    "DiskNoteStorage",
+    "FileLedger",
+    "InMemoryLedger",
+    "InMemoryNoteStorage",
+]