Onyx Writer

Onyx Writer is a local-first editor for Open Knowledge Format bundles. A bundle is a folder-backed OKF document space that Onyx Writer indexes and manages as one unit. The app uses Tauri for the desktop shell, flat files for document storage, Tiptap for visual editing, and CodeMirror for raw OKF editing.

The app also includes a JSONM design-system runtime. JSONM definitions are validated and compiled into constrained CSS variables for the app shell, editor, validation panel, and document preview surface. Bundled archetypes ship with the app, while imported JSONM files are stored as app configuration outside OKF bundles.

Status

Onyx Writer 0.1.19 is the current public source release. It includes OKF v0.2 authoring and migration, actor error disambiguation, and lossless managed-frontmatter updates with explicit audited clearing through the CLI and MCP. v0.1.19 does not publish application binaries or updater artifacts. v0.1.15-alpha remains the latest prebuilt and updater-enabled public release. Keep backups of important bundles and treat both lines as early software.

OKF capability matrix:

• Reads: OKF 0.1 and 0.2, including undeclared bundles on a best-effort basis.
• Authors: OKF 0.2 for newly created bundles and explicit v0.2 writes.
• Existing 0.1 and undeclared bundles are never silently upgraded on open or save.
• The validator implements the v0.2 consumer obligations, and the authoring paths produce conformant OKF v0.2 bundles when required metadata is supplied.

Features

• Visual and raw editing modes for OKF Markdown documents.
• Flat-file bundle storage with no document database.
• Multi-document tabs, autosave, validation feedback, and document tree management.
• Active document status metrics for inbound links, outbound links, words, and visible-text characters.
• Local Mermaid rendering with zoom, pan, fit, and reset controls.
• Interactive bundle graph with folders, documents, internal links, broken links, local physics, hover focus, and node selection.
• JSONM-driven app theming with bundled design-system archetypes and local imports.
• Developer-project safeguards for OKF bundles nested inside source repositories.
• Governed local agent access through standalone onyx CLI and onyx-mcp stdio executables bundled with the desktop application.
• Explicit actor-aware OKF v0.2 authoring across desktop, CLI, MCP, and new protected content.
• Managed standard-directory v0.2 frontmatter preservation, structured agent reads, and explicit audited metadata clears across CLI and MCP.
• Opt-in standard-directory v0.1 to v0.2 migration with dry-run plans, source-drift detection, complete checksummed recovery copies, rollback, and restore drills.
• Experimental protected bundle storage with local encryption, passphrase-gated desktop unlock/edit/save, protected document/folder CRUD, protected-copy creation, and CLI workflows.

Distribution

The v0.1.19 prerelease is source-only. Its manually attached release assets are a deterministic source archive and SHA256SUMS; generated source links may also appear in the GitHub interface. Do not treat locally built, ad-hoc-signed applications as release assets or updater candidates.

To build 0.1.19 locally, follow Setup and Desktop Packaging.

The v0.1.15-alpha GitHub release includes:

• macOS Apple Silicon DMG
• macOS updater .app.tar.gz archive and signature metadata
• Linux DEB package
• Linux RPM package
• Windows x64 MSI installer and NSIS setup executable
• Windows ARM64 MSI installer and NSIS setup executable
• latest.json updater metadata
• Generated signatures and SHA-256 asset digests where produced by the release workflow

The macOS app is not signed or notarized yet, so macOS may show a warning on first launch. Linux AppImage builds are not part of this alpha.

v0.1.15-alpha remains discoverable from prior updater-enabled builds through its signed macOS and Windows updater paths. Linux DEB/RPM packages remain manual update assets. The source-only v0.1.19 release does not replace latest.json or participate in that updater channel. See docs/release/auto-updates.md.

Setup

Source builds are verified with Node.js 24.17.0 LTS, npm 11.13.0, and Rust 1.97.1; the Rust crate declares 1.77.2 as its minimum supported compiler. Tauri also requires Xcode Command Line Tools on macOS, WebView2 and Microsoft C++ build tools on Windows, or the native WebKit/GTK packages documented in Linux Build.

git clone https://github.com/activetwist/OnyxWriter.git
cd OnyxWriter
git checkout v0.1.19
npm ci

Verify the source checkout before packaging:

npm run typecheck
npm run test
npm run build
npm run tauri:check
npm run agent:build
npm run agent:verify
npm run license:check

Create a local application without updater artifacts:

npm run tauri:build:local

The application is written beneath src-tauri/target/release/bundle/; on macOS the bundle is src-tauri/target/release/bundle/macos/Onyx Writer.app. Local builds are unsigned or ad-hoc signed, are not notarized, and must never be uploaded as public release or updater assets.

After installing from the local application, open Settings → Agent Access, choose Install command-line tools, and verify the CLI:

onyx --version
onyx version --json

MCP clients receive the same application version in the stdio server's initialize response. The Agent Access panel generates a configuration using the bundled onyx-mcp executable's absolute path.

Development

npm run dev
npm run tauri:dev

The browser dev server includes a sample bundle preview. Full filesystem open/save flows run inside Tauri. In the desktop runtime, Onyx Writer attempts to restore the most recent bundle on startup and falls back to the bundle chooser if that folder is unavailable.

Verification

npm run typecheck
npm run test
npm run build
npm run tauri:check
npm run agent:build
npm run agent:verify
npm run license:check

Security/dependency checks for the current release line:

npm audit --audit-level=high

Storage Model

User documents remain Markdown files in the selected Onyx bundle directory. Onyx Writer does not store user document content in SQLite or another document database.

An Onyx bundle is a user-selected folder containing flat-file OKF documents, reserved system files, generated index boundaries, and managed bundle-local assets. index.md and log.md are reserved system files; the document tree hides them by default and can reveal them from Settings. Generated index.md files may exist at the root and inside subdirectories. The generated portion is bounded by <!-- onyxwriter:index:start --> and <!-- onyxwriter:index:end --> so prose outside that block is preserved.

Images inserted from the desktop app are copied into assets/images/ inside the active bundle and referenced from Markdown with relative paths.

Application settings live outside bundles. Imported JSONM design systems and the active design-system id are stored in the Tauri app-data directory, while browser preview mode uses localStorage. Recent bundles are app settings; OKF Markdown, bundle assets, and generated index.md content stay in the bundle.

Onyx Writer does not create .onyxwriter, .obsidian, or other hidden app-private folders in source projects by default. If you use OKF alongside code, prefer a nested bundle such as docs/okf/ or knowledge/ instead of opening the whole repository root as a bundle. See docs/guides/okf-in-code-projects.md.

For agentic IDE workflows, Onyx Writer can also be used as a private document observability surface in a .plandocs bundle. See docs/guides/onyx-agent-authoring.md for portable Codex, Claude, Cursor, and Windsurf authoring instructions.

The onyx CLI and onyx-mcp stdio sidecar expose governed local bundle operations for agents and scripts. See docs/guides/onyx-cli.md and docs/guides/onyx-mcp.md.

Use Settings → OKF Authoring to save an explicit actor identity before writing a v0.2 concept. Use Settings → OKF Migration only when intentionally upgrading a standard directory bundle that declares 0.1. Migration never runs from open, save, create, update, index refresh, protection, or MCP.

In the packaged macOS application, open Settings → Agent Access and choose Install command-line tools. Onyx Writer installs guarded user-owned links under ~/.local/bin and generates MCP JSON using the bundled sidecar's absolute application path. The installed tools do not require Node.js or a source checkout.

Protected bundle storage is experimental. Onyx Writer can create encrypted folder-backed protected bundles from Settings, prompt for the passphrase when a protected bundle is opened through the normal bundle picker, create a protected copy of the current standard bundle, and perform document/folder CRUD after unlock. Protected bundles store only encrypted manifests and encrypted document objects on disk. See docs/guides/encrypted-bundles.md.

Editing and Autosave

Bundle-backed documents autosave after a short debounce using the same scoped Tauri write path as manual save. The toolbar shows Unsaved, Saving, Saved, or Error, and manual save remains available as a fallback. Browser sample bundles are preview-only and do not write to disk.

The document tab strip keeps multiple files open inside a bundle. The toolbar keeps formatting, table, image, link, and undo/redo actions as the primary editing controls. The Visual/Raw selector lives with the save status as a utility control.

Visualizations

Mermaid fenced blocks render as native visual previews in Visual mode and remain raw-editable in Raw mode. Each rendered diagram includes local zoom, pan, fit, and reset controls. Mermaid rendering uses the bundled dependency only; diagrams are not loaded from a CDN.

The bundle graph button opens an SVG map of the active bundle. The graph includes folders, documents, document links, and broken internal links, while reserved system files remain hidden unless system-file visibility is enabled. The graph uses local D3 physics with animated settling, draggable nodes, hover/focus neighborhood highlighting, and fit/reset controls sized to the current work surface. Document nodes can be selected from the graph to open the underlying Markdown file.

JSONM Themes

The active JSONM design system styles the app shell, bundle rail, editor and raw editor surfaces, settings, validation states, toolbar, and design-system preview through constrained --ow-* token aliases. Appearance mode changes apply to the runtime app, not only to the preview panel.

Enterprise Clean is the default bundled design system for first run and reset.

Repository Hygiene

This product repository intentionally excludes local planning/runtime material such as Command Deck state, agent workflow files, .plandocs, local MCP configuration, generated builds, and machine-specific environment files. See docs/release/push-hygiene.md for the publication workflow.

Known Limitations

• Attested Computation, trust-tier/lifecycle rendering, and automatic upstream drift detection are deferred; the v0.2 consumer and authoring metadata families are supported without claiming those deferred features.
• Managed-frontmatter preservation applies to standard-directory CLI and MCP writes; encrypted-folder and sealed write paths do not yet share that guarantee.
• Protected-bundle document.delete remains unverified on every release host.
• Metadata lost by an earlier destructive update cannot be reconstructed automatically; restore it from a known-good copy or version-control history.
• Complex Markdown should be reviewed or edited in Raw mode when the validation/confidence rail says so.
• macOS builds are unsigned and not notarized.
• Linux AppImage packaging is not available yet.
• v0.1.19 is source-only; v0.1.15-alpha remains the latest prebuilt/updater-enabled release.
• Existing Windows x64 and Windows ARM64 packages should still be treated as alpha packages.
• Protected bundle storage is still experimental; keep recoverable backups while the alpha line matures.
• There is no cloud sync, account system, collaboration, or hosted storage.

Contributing and Support

See CONTRIBUTING.md, SUPPORT.md, and SECURITY.md. The project is MIT licensed; see LICENSE and THIRD_PARTY_NOTICES.md.