Done! I just published the full workflow documentation today:
AI Development Workflow: Complete explanation of the process, handover system, how I manage context between sessions
Historical PRDs: The actual Product Requirements Documents used to generate tasks (v0.1.x through v0.3.0)
Task JSON files: How requirements were broken down into implementable tasks via Task Master
Handover templates: The reusable prompts I use to maintain context between AI sessions
Thanks for pushing on transparency, your comment about "open weights vs open source" is a useful framing. The goal is to share enough that someone could reproduce and learn from the approach.
Actually, this is going on the v0.3.0 roadmap. I've been looking for ways to make the standalone mermaid-rs crate genuinely better than just 'mermaid.js but Rust.'
The plan: use %% comments as layout hints. Something like:
%% @pos NodeA 100 200>
Mermaid.js ignores these, so the diagram stays portable. But Ferrite (and anyone using mermaid-rs) could parse them for manual positioning.
You'd be able to drag nodes around in Ferrite, have positions saved to the source, and still share with mermaid.js users (they'd get auto-layout).
If you want to follow progress or have input on the syntax, feel free to open an issue on the repo!
You're right, neither Mermaid nor D2 really nail AWS architecture diagrams out of the box. Mermaid lacks icons entirely, and D2's AWS pack is more 'icons exist' than 'architecture patterns are easy.'
Honestly, this is a gap in the ecosystem. For now, most people either:
- Use draw.io/Excalidraw despite the pain
- Build diagrams programmatically (Diagrams-as-code Python library has good AWS support)
- Just accept text-based flowcharts without icons
If I add custom icon/shape support to Ferrite's Mermaid renderer (v0.3.0+), AWS icons could be a good test case. No promises, but I hear the frustration.
The challenge is Mermaid is declarative — layout is computed, not specified. Some options I'm considering:
1. layout hints/constraints in the syntax,
2. export to SVG then use a proper editor like Excalidraw for repositioning. For now, influencing layout via subgraphs and edge ordering is the best workaround."
3. separate system for that, maybe to be included in the crate, would only work in Ferrite in the start
the line is blurry for shure. Code generated by a closed-source compiler (or LSP) is still 'your' code. Maybe the difference is whether humans can reproduce and learn from the process? With traditional code, you can read commit history and understand the author's thinking. With AI-generated code, that context is lost unless explicitly shared. Food for thought.
Great point about sharing the 'how' not just the 'what'. I'll consider adding prompt history or a development log showing the AI interactions, just have to figure out how to present all the data i guess. The commit messages could definitely include more context about what was requested vs generated. Thanks for the thoughtful framing,'open weights vs open source' is a useful distinction
Thanks! TeX math support ($...$ and $$...$$) is planned for v0.4.0. We're going pure Rust (no JS runtimes), targeting common LaTeX syntax. See the planning doc on github (docs folder) for details.
Mobile is definitely a long-term goal, the lightweight binary and native performance would translate well. Your QR-code pairing idea is elegant for non-technical users.
For sync, I've been thinking about:
- Git-based sync for power users (already have git integration)
- Simple local network sync (mDNS discovery, no cloud required)
- Optional relay server, as you described — small binary for hub-and-spoke
The plain-file approach (no proprietary format) makes this tractable since any sync tool works today (Syncthing, Dropbox, etc.). But a native, frictionless solution would be better.
2. Tool Integration API
This aligns with v0.3.0's direction. The plan is:
- Mermaid crate extraction, establishes the modular pattern
- Editor widget as library, opens up embedding
- Command palette / IPC, could expose operations to external tools
For accessibility specifically, what interfaces work well for you? Shell commands? Named pipes? JSON-RPC? Knowing your workflow would help prioritize.
3. Vaults/Profiles
Good point — workspace settings are currently per-folder (`.ferrite/`), but there's no concept of isolated plugin configurations per vault. Added to the consideration list.
I tried to add it for this release but hit a wall with the font rendering dependencies (freetype, fontconfig). GUI apps need these for text display, and they don't play well with fully static musl linking - the build system wants a musl C++ cross-compiler and static versions of system libraries that aren't readily available in CI.
We'll keep looking into options - possibly a Docker-based build with a proper musl toolchain, or investigating if we can make fontconfig use dlopen at runtime. For now the glibc build (Ubuntu 22.04) should run on most Linux distros.
If anyone has experience with static musl builds for Rust GUI apps, we'd love to hear what's worked!
You raise a fair point, and I've thought about this a bit since you mentioned it.
What those files actually are:
The files you noticed (AGENTS.md, GEMINI.md, CLAUDE.md, etc.) are auto-generated scaffolding from Task Master AI, a task management tool I use. They contain MCP (Model Context Protocol) configuration for various AI coding assistants — essentially boilerplate instructions for how different AI tools should connect to the task system. They're not really "coding conventions" so much as tool-specific wiring.
That said, you're right that it would be useful to share the actual conventions and rules I use, especially for an AI-generated project.
What I'd be happy to share:
My Cursor system prompt — I have a general coding principles prompt I use across projects. It's not Ferrite-specific but covers code style, architecture preferences, etc. Happy to share this.
Project-specific rules — I do have .cursor/rules/ files with Task Master workflow conventions. These could be included if contributors want to use similar AI-assisted workflows.
The actual workflow — How I structure tasks, iterate on implementations, and the back-and-forth with AI. This might be more useful than config files.
Why I excluded them initially:
Honestly, most of those files are boilerplate MCP configs that would only matter if someone wanted to use the exact same tooling stack (Cursor + Task Master + specific MCP servers). I wasn't sure that would be useful to most contributors, and I didn't want to clutter the repo with tool-specific noise.
But I take your point about setting conventions for AI-assisted contributions.
Let me know if there's interest, and I can:
Add a CONTRIBUTING_AI.md or similar with the actual conventions and workflow
WYSIWYG — This is where it gets nuanced. Ferrite has three modes:
- Rendered mode — Click-to-edit rendered Markdown (closest to WYSIWYG)
- Split view — Raw editor + live preview side-by-side
- Raw mode — Plain text editing
It's not pure "type and it formats inline" like Typora or Confluence. The Rendered mode lets you click elements to edit them, but it's not seamless WYSIWYG yet.
If you're looking for true inline WYSIWYG, Typora is probably closest. But if split view + rendered mode works for you, give Ferrite a try — it hits the other criteria well.
The TODO list cursor behavior is exactly the kind of polish detail that matters. I'll add this to the issue tracker — cursor should respect line start position, not jump past the checkbox syntax.
These "many small details" are what v0.3.0's custom editor widget will unlock. egui's TextEdit doesn't give us fine-grained cursor control, but replacing it will.
Interesting use case! Mermaid doesn't have native AWS icons, but for v0.3.0's standalone crate, we could potentially support custom shapes/icons. D2 has better icon support if you need that now.
What specific diagram types do you need — network topology, service flows, infrastructure layout?
Yes, there's a person! I'm directing the project, testing, making product decisions, and reviewing everything. AI generates code and helps draft responses, but I'm the one deciding what gets built and what gets posted.
Good to know! Inline + display math is a more tractable scope. Typst or a Rust KaTeX port could handle that without needing full LaTeX. Added to the consideration list with that clarification.
You're right, currently Ferrite leans developer/tech with Mermaid, JSON/YAML tree viewer, and CLI integration. The Obsidian-style features (wikilinks, backlinks, knowledge graph) are coming in v0.3.0.
Target audience is probably "developers who take notes" rather than pure writers. The native performance angle is the differentiator, same niche as "I want Notion but faster" or "Obsidian but lighter."
Fair feedback! You're right — Ferrite isn't Obsidian-complete. Those are reasonable additions:
- Left panel already exists (file tree + outline), but could use polish
- Right panel (backlinks?) would come with v0.3.0 wikilinks work
- Hiding toolbar is a quick settings addition — I'll add that to the list
What's your priority order for those? And if you do implement encryption later, I'd love to see the approach!
Thanks for the repro steps! This is helpful, formatting bar interaction shouldn't spin up the fan for such a small document. v0.2.2 has some performance improvements and is out, so it might be better, but this specific case might need investigation.
AI Development Workflow: Complete explanation of the process, handover system, how I manage context between sessions
Historical PRDs: The actual Product Requirements Documents used to generate tasks (v0.1.x through v0.3.0)
Task JSON files: How requirements were broken down into implementable tasks via Task Master
Handover templates: The reusable prompts I use to maintain context between AI sessions
Thanks for pushing on transparency, your comment about "open weights vs open source" is a useful framing. The goal is to share enough that someone could reproduce and learn from the approach.