Metadata-Version: 2.4
Name: onyx-vault
Version: 1.0.11
Summary: An open-source, AI-native framework for Obsidian vaults: opt-in modules, a declarative reconciliation engine, and agent-optional workflows.
Project-URL: Homepage, https://github.com/odysseia06/onyx
Project-URL: Repository, https://github.com/odysseia06/onyx
License-Expression: MIT
License-File: LICENSE
Keywords: agent-skills,claude-code,knowledge-management,obsidian,pkm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Onyx

[![PyPI](https://img.shields.io/pypi/v/onyx-vault.svg)](https://pypi.org/project/onyx-vault/)
[![CI](https://github.com/odysseia06/onyx/actions/workflows/ci.yml/badge.svg)](https://github.com/odysseia06/onyx/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://pypi.org/project/onyx-vault/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Onyx scaffolds and operates a tailored [Obsidian](https://obsidian.md) vault, composed from **opt-in modules**. Pick the domains you care about and Onyx wires up the folders, typed frontmatter, [Bases](https://help.obsidian.md/bases) views, and templates for each. The same framework serves a researcher, a PhD student, a musician, and a product manager, with different module sets and different folder names.

Three things hold true everywhere:

- **It works without any AI.** Templates are plain copies, views are plain files. Optional Claude Code skills and agents amplify the vault, but nothing depends on them.
- **It never clobbers your files.** Every file Onyx writes is tracked. A file you edited is yours: updates that would overwrite it arrive as a `*.new` sibling instead, never a silent overwrite. There is no flag that overrides this.
- **It's tailored to you.** Folder names, cadences, and structures are per-vault variables, not baked-in opinions.

## Install

### In Claude Code (nothing to set up)

```
/plugin marketplace add odysseia06/onyx
/plugin install onyx@onyx
/vault-bootstrap
```

The plugin ships the interview wizard. On first run it installs the CLI for you and walks you from an empty folder, or an existing vault, to a working setup.

### As a command-line tool

```
uv tool install onyx-vault      # or:  pipx install onyx-vault
```

Then create a vault:

```
onyx init my-vault                                  # interactive interview
onyx init my-vault --answers researcher-developer   # or start from a profile
```

Open the folder in Obsidian and you're done.

### From source

```
git clone https://github.com/odysseia06/onyx && cd onyx
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Using it

| Command | What it does |
|---|---|
| `onyx init <folder>` | Create a new vault from the interview or a profile. Refuses a non-empty folder. |
| `onyx adopt <vault>` | Bring an **existing** vault under management. Additive only, behind a reviewed plan. |
| `onyx add <module>` | Enable a module (its dependencies come with it). |
| `onyx remove <module>` | Disable a module. Deletes only unmodified framework files; your edits stay. |
| `onyx update` | Pull newer module and skill versions. Files you changed are never overwritten. |
| `onyx plan` / `onyx apply` | Preview the diff, then reconcile. Every mutating command takes `--dry-run`. |
| `onyx doctor` | Check the vault against its declared intent. Read-only. |
| `onyx modules` | List available modules with their variables and defaults. |
| `onyx module new <id>` | Scaffold your own module. |

**Adopting an existing vault is the safe path.** `onyx adopt <vault> --dry-run` is read-only: it maps your existing folders onto module variables, proposes a purely additive plan, and parks anything ambiguous on a checklist instead of touching it. Nothing is moved, renamed, deleted, or overwritten. There is no `--yes` on `adopt` — you review the plan and confirm it, by passing back the token the review prints. (Commit your vault to git first; Onyx will remind you.)

## How it works

The engine is a small CLI built on a declarative reconciliation loop:

- `.vault/config.yaml` declares **intent** — which modules, with which variables. Yours to edit.
- `.vault/lock.json` records **state** — every file Onyx has written, with its hash. Machine-maintained.
- `onyx plan` computes the difference; `onyx apply` reconciles it.

Every file Onyx writes is one of two kinds. **Managed** files (templates, views, skills) update themselves while you leave them alone, and turn into `*.new` deliveries the moment you customize them. **Seeded** files (your home note, a strategy note) are written once and yours from then on. Everything else in the vault is invisible to Onyx, and it will never write there.

## Modules

| Module | What it gives you |
|---|---|
| `core` | The shared conventions, the `Templates/` root, and the home note every module builds on. |
| `daily-notes` | One note per day with task-rollover queries (due, scheduled, overdue, carry-over, captured) and natural-language task capture. |
| `academic` | Courses from a copy-per-course template; exam prep tracked through a Base. |
| `fitness` | Training, nutrition, and body tracking, driven by a Strategy note you own. |
| `research` | A typed paper pipeline: PDF to summary to topic links, over a multi-view Paper Library Base. |
| `reading` | An Inbox to Articles to Evergreen pipeline, with web clipping. |
| `projects-software` | Per-project devlogs, decision logs, subsystem notes, and a task Base. |
| `projects-gamedev` | Game projects as living wikis: design, mechanics, worldbuilding, devlog. |
| `oss` | Open-source tracking from watchlist to contribution, with staleness-aware Bases. |
| `music` | Theory, practice, composition, production, listening, and copy-per-piece projects. |
| `writing` | An editorial blog pipeline: ideas to drafts to published, with series and a calendar. |
| `ai-workspace` | A prompts library and an agent-skills workbench. |

Enable any combination with `onyx add`, or start from a **profile** (a named module set): `minimal`, `fitness-focused`, `student`, `phd-student`, `writer`, or `researcher-developer`.

## The agent layer (optional)

When you use Claude Code, each enabled module installs scoped skills and a per-domain agent into `.claude/` — `daily-planner`, `research-librarian`, `study-coach`, `fitness-coach`, and so on, each with explicit read/write boundaries. A generated `CLAUDE.md` orients Claude the moment you open the vault, pointing at the agents and the operating rules so a plain request reaches the right one; other runtimes get a generated `AGENTS.md`.

These agents don't only suggest — they **operate the live vault** through Obsidian's official command-line interface: scaffold and triage the day, capture a task from a sentence (*"add a task to fix this by Friday"*), log a coding session or record a decision (*"we decided X because Y"*), file a typed paper summary, and so on — you reach the right agent just by saying what you want. Every write follows one contract (the `vault-operations` skill): additive by default, inside the agent's scope, escalating rather than guessing — so the never-clobber guarantee holds for agents too. Delete `.claude/` entirely and the vault still works as plain files; the agent layer is power, never a dependency.

## Documentation

- **[KICKSTART.md](KICKSTART.md)** — the full design document: vision, architecture, the module system, and the write/lock/update contract.
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to work on Onyx and author modules.
- **[RELEASING.md](RELEASING.md)** — how releases are cut and published.

## License

MIT.
