Initial full release

Vellis — v1.0

This release transforms Vellis from a developer-oriented RTG beta into an installable local knowledge system with guided onboarding, automatic recovery, a built-in Everyday Life ontology, and a formally validated SysML v2 design foundation.

Highlights

• One-command setup for Codex, Claude Code, Claude Desktop, and generic MCP clients.
• Automatic durable-state recovery across MCP process restarts.
• Built-in, extensible Everyday Life ontology with no invented user data.
• Textual SysML v2 established as the normative design authority.
• Expanded RTG querying, validation, compact responses, and recovery evidence.
• Native Windows onboarding and MCP smoke-test coverage.
• Test suite expanded from 161 to 324 passing tests.

Simplified Installation and Onboarding

Ordinary users can now install and connect Vellis with:

git clone https://github.com/volantlabs/vellis.git
cd vellis
uv run vellis setup

Setup now:

• Detects Codex, Claude Code, Claude Desktop, or a generic JSON MCP client.
• Shows the exact launch, configuration, and data paths before making changes.
• Requests one confirmation before modifying user-wide MCP configuration.
• Generates cwd-independent configuration with absolute executable and storage paths.
• Recovers an existing durable graph before accepting connections.
• Installs the starter ontology only when the graph is genuinely empty.
• Preserves unrelated MCP registrations and is idempotent when repeated.
• Fails closed without changing client configuration when recovery or validation fails.

A new non-destructive diagnostic command is available:

uv run vellis doctor

For scripts and agents, setup --json and doctor --json emit exactly one JSON document and never prompt. Non-interactive setup requires explicit authorization through --yes.

The shorter vellis console command is now available while vellis-rtg-knowledge-graph remains supported for compatibility.

Everyday Life Ontology

New installations include a modeled, schema-only Everyday Life ontology for organizing personal, household or family, and work information.

It includes anchors for:

• People and groups.
• Areas of responsibility.
• Goals, projects, and tasks.
• Events and routines.
• Decisions and notes.
• Resources and places.

Typed relationships cover responsibility, membership, support, location, documentation, mentions, dependencies, and other common connections.

The ontology:

• Contains no people, tasks, or other user facts.
• Requires only a name or title, allowing incomplete but truthful records.
• Uses deterministic identities and an idempotent installation process.
• Can be extended after installation.
• Never overlays a recovered custom schema merely because type names overlap.
• Rejects incompatible identity collisions and partial installations without mutation.
• Is generated from the normative Vellis model rather than maintained as a separate hand-authored contract.

Automatic Recovery and Safer Upgrades

Ordinary startup now reconstructs live graph, schema, constraint, and migration state from the durable SQL ledger before the MCP server accepts connections.

Recovery improvements include:

• Automatic ledger replay after process restarts.
• Post-replay validation with fail-closed startup behavior.
• Exact domain-state equivalence checks using digests, not counts alone.
• Separate reporting of domain-state and ledger-cursor equivalence.
• Detailed replay accounting for scanned, eligible, replayed, administrative, rejected, and terminal records.
• Durable migration history for applied, abandoned, failed, and rejected schema proposals.
• Preservation of custom schemas from earlier beta installations.

Explicit recovery remains available for evaluation and audit workflows through --manual-recovery. The --empty option disables starter-schema installation without rejecting healthy recovered custom state.

RTG Query and Validation Improvements

The query engine now supports:

• Deterministic limit and offset pagination.
• Distinct projected rows.
• Grouped count aggregation over distinct UUID bindings.
• Optional and chained optional link requirements.
• Exact, kind-sensitive recursive JSON equality.
• Arbitrary-precision JSON integer ordering and grouping.
• Expanded comparison, membership, string, and regular-expression predicates.
• Explicit case-sensitivity and regular-expression flags.
• RE2-compatible regular expressions for predictable execution.
• Stronger validation of ambiguous bindings, return paths, aggregation names, and incompatible options.

Schema and change validation now cover:

• Recursive object and array field definitions.
• Required fields and nested strictness.
• Allowed values, numeric bounds, string lengths, and RE2 patterns.
• Coherent and unique field-kind combinations.
• Grouped and global cardinality constraints.
• Distinct-target counting.
• Canonical set handling and duplicate rejection.
• Boundary-specific failures and structured corrective diagnostics.
• Atomic snapshot import and stronger no-effect guarantees on rejection.

More Efficient MCP Responses

The 27-tool MCP surface remains intact while response shaping is more efficient and predictable.

Notable improvements include:

• Compact mutation responses are now the default for anchor-record ingestion.
• Compact responses preserve generated anchor, fact, and link UUID mappings.
• Beta-scale compact mutations are verified to be at least 60% smaller than full responses.
• Full canonical mutation payloads remain available through format: "full".
• Query responses explicitly identify full and properties_only result kinds.
• Snapshot operations can return compact summaries without embedding the complete snapshot.
• Schema staging correlates generated UUIDs by kind:type_key.
• Capability guidance describes tool lanes, dry-run predecessors, mutation behavior, and intended audiences.
• MCP tool metadata is generated from the application model and kept within defined size limits.

SysML v2 Design Authority

Textual SysML v2 under model/ is now the normative black-box design for the repository.

The repository explicitly separates three model products:

• Software Component Modeling Foundation — reusable lifecycle, realization, state-access, failure, and evidence vocabulary.
• Bibliotek — the reusable AI-native component library.
• Vellis — the application composition, façade, actor-visible use cases, ontology, and Python/MCP realizations.

Foundation and Bibliotek are independently packageable library products. Vellis consumes Bibliotek, while Bibliotek remains independent of Vellis.

The model now captures:

• Typed public actions and values.
• Collaborator roles and application composition.
• Abstract owned and derived state.
• Action effects and no-effect failure behavior.
• Component and application invariants.
• Actor-visible use cases.
• Python and MCP realization mappings.
• Requirements, asserted satisfiers, verification objectives, and concrete evidence bindings.
• The canonical 27-tool Vellis façade.

Formal Model Validation and Generated Evidence

New model tooling provides:

• Independently packaged Foundation, Bibliotek, and Vellis KPAR products.
• Validation through a checksum-pinned official Java SysML v2 validator.
• Architecture and dependency-direction checks.
• Public-contract and implementation-binding checks.
• Generated-artifact freshness validation.
• Human-readable Bibliotek component and Vellis application references.
• Machine-readable parser inventories, conformance objectives, and verification-evidence indexes.
• A generated runtime MCP manifest.
• Model-to-implementation handoff reports.
• Read-only model/implementation hygiene audits.

The repository also includes a searchable, checksum-verified Markdown projection of the pinned SysML and KerML specifications. The official PDFs remain authoritative.

Agent and Contributor Tooling

Repository-local agent skills have expanded from four to seven and now cover:

• Component authoring.
• Python component implementation.
• Documentation synchronization.
• RTG Knowledge Graph MCP operation.
• RTG schema design.
• SysML/KerML reference research.
• Model/implementation hygiene review.

Generated documentation replaces the previous hand-authored component-contract pages, eliminating a parallel source of truth.

Cross-Platform and CI Improvements

• Added native Windows MCP configuration and onboarding smoke tests.
• Added PowerShell-safe path and argument quoting.
• Added focused MCP configuration output for Codex and JSON-based clients.
• Added repository-layout and documentation-link validation.
• Added formal model setup and validation to CI.
• Updated FastMCP from 3.4.3 to 3.4.4.
• Updated Ruff from 0.15.20 to 0.15.21.
• Added the pinned google-re2 runtime dependency.
• Added locked Windows wheels for supported RE2 platforms.

Upgrade Notes

Existing v0.1 or Private-Beta Data

Existing graphs do not require a logical data migration. Preserve the exact --storage-root and --sql-database-path values from the current MCP registration and run:

uv run vellis setup \
  --storage-root /absolute/path/from/the-existing-registration \
  --sql-database-path /absolute/path/from/the-existing-registration/controller.sqlite

Then run vellis doctor with the same arguments, restart the MCP client, and verify system state and graph validation before moving or deleting the original data.

Do not substitute --data-dir for a legacy flat --storage-root; the two options describe different layouts.

Startup Behavior

Normal startup now performs automatic replay and installs the Everyday Life ontology only for a genuinely empty graph....

Initial beta

Vellis v0.1.0

Vellis v0.1 is the first public beta of a reusable AI-native component library and its first reference application: a local Reified Typed Graph (RTG) knowledge system for humans working with AI agents—and agents working independently.

Highlights

• Turnkey local RTG Knowledge Graph accessible through MCP.
• Nine reusable, accepted component contracts with Python reference implementations.
• Schema evolution, validation, migration, querying, audit, snapshots, restore, and ledger replay.
• Agent-facing guidance, structured diagnostics, and recovery workflows.
• Clone-and-run environment built around Python 3.14, uv, and just.
• Markdown-based development and component workflows.

RTG Knowledge Graph

The first Vellis application composes the component library behind a 27-tool MCP interface supporting:

• Graph CRUD with dry-run validation and batch anchor ingestion.
• Schema bootstrap and evolution through staged migrations and controlled cutover.
• Declarative graph queries, exact anchor resolution, type discovery, and schema packs.
• System-state summaries and packaged usage guides that help agents select appropriate workflows.
• Transaction IDs, SQL-backed ledger positions, migration history, and queued audit failures.
• Snapshot export, persistence, loading, restore, replay, and non-mutating replay verification.
• Structured, path-specific diagnostics that help agents repair invalid requests safely.

Both stdio and unauthenticated localhost HTTP MCP transports are available. Generated client configuration includes absolute paths and a recommended connection smoke test.

Component Library

This release includes accepted contracts, protocols, reference implementations, and boundary tests for:

• JSON document storage with bounded paths and atomic replacement.
• SQLite-backed SQL execution and transactions.
• Schema-neutral reified typed graphs.
• RTG schema and constraint-definition stores.
• Migration lifecycle and cutover records.
• Declarative RTG graph querying.
• Deterministic, non-mutating change validation.
• System-level RTG orchestration, validation, snapshots, recovery, audit, and replay.

A future curated discovery-view component is documented as a draft. Vellis v0.1 provides basic discovery through composed schema summaries and graph counts.

Agent and Contributor Experience

• Repository-local skills for component authoring, Python implementation, documentation synchronization, and RTG MCP operation.
• Manual evaluation materials covering an individual life graph, agent affordances, operational sequencing, and a known-good walkthrough.
• Component contracts documenting responsibilities, owned state, dependencies, invariants, failures, and black-box verification expectations.
• Apache-2.0 licensing, contribution guidance, security reporting, issue templates, Dependabot, and CI.

Known Limitations

• Live graph, schema, constraint, and migration state uses in-memory component realizations during execution; no disk storage-only option currently.

Release Verification

The release snapshot was verified with:

• 161 passing tests.
• Ruff lint checks.
• BasedPyright with zero errors, warnings, or notes.
• Validation of all four repository-local agent skills and Claude skill links.
• Successful source-distribution and wheel builds.

Full Changelog: https://github.com/volantlabs/vellis/commits/v0.1