DEV Community: Vivek Maskara

Building Modular Monoliths With Kotlin and Spring

Vivek Maskara — Thu, 15 Oct 2026 21:42:37 +0000

Over a decade ago, Netflix became one of the early adopters of microservice architecture, showcasing its potential at a large scale. Since then, many companies have jumped on the microservices bandwagon, building their backends this way from day one. While microservices offer isolation and independent scaling, their distributed nature requires managing multiple deployments, monitoring interservice communication, and handling network failures across service boundaries.

As teams have gained real-world experience with this complexity, there's been a shift back toward monoliths, but not the tightly coupled monoliths of the past. Instead, developers are embracing modular monoliths: an architectural pattern where single deployable applications are organized into well-defined modules based on logical boundaries or business domains. Think of an e-commerce platform where users, products, and orders live in separate modules that interact through clear contracts, such as APIs for synchronous calls and events for async communication. This separation lets teams work in parallel for faster development and better maintainability, while single-unit deployment keeps releases simple and avoids microservice operational complexity.

In this guide, we explore how modular monoliths differ from traditional monoliths, why they're gaining traction, and how to build them using Spring Modulith and Kotlin.

The Need for Modular Monoliths

The growing modular monolith countertrend makes more sense when viewed against the shortcomings of traditional approaches.

Traditional monoliths bundle the entire backend into a single codebase with tight coupling between user interfaces, business logic, and data access patterns. In an e-commerce platform, for example, the product catalog, checkout, payments, and order history services are in a single codebase and are deployed together. A monolith uses function calls for internal communication, and often, the call patterns and interdependencies become messy or difficult to maintain.

Microservices emerged to solve these maintainability challenges by splitting backends into loosely coupled services, each handling a specific domain. A cab-hailing platform may separate users, drivers, ride matching, payments, and notifications into independent services. However, this introduces distributed system challenges, including complex service discovery, coordinating deployments across dependent services, and debugging interservice communication issues. Without proper expertise, tooling, and observability, this can slow down development.

Modular monoliths strike a balance by keeping everything in a single codebase and deploying it as one artifact, while structuring the application into logical modules with well-defined interfaces. This addresses the challenges of distributed systems while maintaining the structural benefits of well-defined interfaces and independent development workflows. Some benefits of a modular monolith include:

Simplified deployment: A single deployment artifact simplifies the release process because you don't need to coordinate multiple service rollouts, manage service meshes, or handle distributed database migrations and rollbacks.
Reliable testing: As modules in a monolith communicate in-process rather than over a network, integration tests are faster and more stable. You can use mocks where needed, avoid brittle network dependencies, and run end-to-end (E2E) and performance tests in a controlled environment.
Stronger domain modeling: Modular monoliths group related business logic into modules, with clear ownership and communication boundaries between modules. It enforces communication only through well-defined interfaces and enables domain objects to be shared directly without serialization or cross-service APIs. This makes the system easier to maintain and improves development velocity.
In-process communication: Since modules communicate through direct method invocations instead of network calls, it reduces latency and points of failure.

Designing a Modular Monolith

When you're building a modular monolith, you first identify the business domains and split the application into multiple loosely coupled modules with clear boundaries and dependencies. Unlike the tightly interwoven code of a traditional monolith, the modular design ensures that the modules can be developed and maintained independently while still being deployed as a single unit. For example, you can break down an e-commerce platform into separate modules such as users, product catalog, shopping cart, payments, and orders:

Each module encapsulates a specific entity or capability. A product catalog module would manage product details and categories, and an order processing module would handle order and payment entities. Unlike traditional monoliths, where internal calls often use ad hoc dependencies, in a modular monolith, the interactions with other modules are performed using explicit interfaces and well-defined contracts. This ensures that the intermodule dependencies remain clear and intentional. The communication between the modules uses in-process function calls, so it's faster and less error-prone compared to network-based interservice calls in microservices.

The modular structure allows logical separation between the modules and enforces fixed boundaries, increasing development speed, improving maintainability, and making testing more reliable. Each module defines its user interface, business logic, and data access layers separately:

These boundaries also lay the groundwork for extracting a particular module as a microservice based on the scaling requirements.

Integrate Spring Modulith

Spring Modulith is a Spring Boot framework that's based on modular monolith architectural principles. It helps identify, structure, and enforce application modules. It also includes tools for verifying module boundaries and observing their behavior, along with module-level testing capabilities, making Spring Boot applications easier to build and maintain.

Here's how to integrate Spring Modulith into a Kotlin-based Spring Boot application.

All the code samples are drawn from a fully working Kotlin example, which you can find in this GitHub repository.

Quick Start Kotlin Example

Spring Modulith can be added to any Spring Boot application by including its dependencies in the project's build.gradle.kts:

// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter")
    implementation("org.springframework.modulith:spring-modulith-starter-core:1.4.3")
}

Note: If your project uses Maven, you can add these dependencies to the pom.xml file.

To define the modules, you need to add relevant package directories to the src directory. This code snippet illustrates order and product packages added to the application, each handling its own business logic, data, and services:

SpringModulithExample
└── src/main/java
    ├── example
    │   └── SpringmonolithApplication.kt
    └── example.order
        └── …
    └── example.product
        └── …
    └── example.payment
        └── …

Within each of the modules, you can define the business logic, service, and data access layers based on your application's requirements. The following code snippet shows a ProductService within the example.product package that returns a static greeting message:

package com.example.springmonolith.product

import org.springframework.stereotype.Service

@Service
class ProductService {

    fun getGreeting(): String {
        return "Hello from Product Module!"
    }
}

Similarly, define an OrderService within the example.order package that invokes ProductService::getGreeting() and returns a combined greeting message:

package com.example.springmonolith.order

import com.example.springmonolith.product.ProductService
import org.springframework.stereotype.Service

@Service
class OrderService(
    private val productService: ProductService
) {

    fun getGreeting(): String {
        return "Hello from Order Module!"
    }

    fun getCombinedGreeting(): String {
        return "Hello from Order Module and: ${productService.getGreeting()}"
    }
}

After adding similar business logic for each of the modules (eg ProductService, PaymentService), you also need to add the @Modulithic annotation to the Spring Boot Application class to mark it as modular. The annotation tells Spring Modulith to automatically detect modules based on package structure and enable the tooling for verification, testing, and observability:

package com.example.springmonolith

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.modulith.Modulithic

// add this annotation to the application
@Modulithic
@SpringBootApplication
class SpringmonolithApplication

fun main(args: Array<String>) {
    runApplication<SpringmonolithApplication>(*args)
}

Next, you can update the package info file for each of the modules to define the allowed module dependencies. Since the order module depends on the methods defined in the product module, you'll need to add the following annotation in the order/package-info.java file:

// add this annotation
@org.springframework.modulith.ApplicationModule(allowedDependencies = {"product"})
@org.springframework.lang.NonNullApi
package com.example.springmonolith.order;

Finally, you can update the product/package-info.java file to set an empty dependency list for the product module:

// add this annotation
@org.springframework.modulith.ApplicationModule(allowedDependencies = {})
@org.springframework.lang.NonNullApi
package com.example.springmonolith.product;

The above annotation ensures that if a class or object defined in the product module tries to invoke a method defined outside the module, Spring Modulith verification tests will flag the violation. You will see an example of this scenario in later sections.

Spring Modulith Features

Spring Modulith supports various tools for working with modules, including module verification, documentation, and runtime observability. With @Modulithic, the application automatically recognizes its modules (based on package structure) and enables the modulith tooling. Let's look at how these work.

Modular Structure Checks

Spring Modulith provides built-in tooling to verify that the module boundaries adhere to the constraints. It checks for cyclic dependencies, validates that modules access other modules only through their public API packages (not internal code), and enforces explicit dependency rules. In your tests, you can use the ApplicationModules.verify() to verify the modular structure:

ApplicationModules.of(Application::class.java).verify()

Refer to the source code on GitHub for a complete example of the ModularityTest. With the above test configured, if the ProductService tries to invoke an order module method, the module verification test will fail. You can test the behavior by extending the ProductService to call getGreeting as shown below:

// add import
import com.example.springmonolith.order.OrderService

@Service
class ProductService(
    private val orderService: OrderService
) {

    // add this after getGreeting()
    fun getCombinedGreeting(): String {
        return "Hello from Product Module and: ${orderService.getGreeting()}"
    }
}

Since product module is configured to disallow all intermodule dependencies, when you run unit tests (./gradlew test), you would get a module violation error as shown below:

— TRUNCATED OUTPUT —
ModularityTests > verifiesModularStructure() FAILED
    org.springframework.modulith.core.Violations at ModularityTests.kt:20

You can replace direct intermodule calls with application events that let one module publish a domain event and another module listens to it. This preserves boundaries and avoids compile-time coupling between modules. For example, the order module can publish an event when an order is created, as shown below:

// order module
import org.springframework.context.ApplicationEventPublisher

@Service
class OrderService(private val events: ApplicationEventPublisher) {

    fun completeOrder(orderId: String) {
        events.publishEvent(OrderCompleted(orderId))
    }
}

data class OrderCompleted(val orderId: String)

Notice that the completeOrder method publishes the OrderCompleted event, and other modules (eg, InventoryPolicy) could react to the event using @ApplicationModuleListener, as shown below:

// product module
import org.springframework.modulith.events.ApplicationModuleListener
import org.springframework.stereotype.Component

@Component
class InventoryPolicy {

    @ApplicationModuleListener
    fun on(event: OrderCompleted) {
        println("Updating inventory for order: ${event.orderId}")
    }
}

Notice that the InventoryPolicy component has a listener configured for the OrderCompleted event that prints the order ID when it receives the event. Refer to the refactor branch on GitHub for a complete example on domain events.

Modular Level Testing

Modulith supports writing integration tests scoped to a single module. You can annotate a test class with @ApplicationModuleTest to test the module and its dependencies in isolation. This avoids the need to spin up the entire application, reducing setup overhead and making tests more reliable. For example, this code snippet shows a bare-bones integration test for the product module:

import org.junit.jupiter.api.Test
import org.springframework.modulith.test.ApplicationModuleTest

@ApplicationModuleTest
class ProductModuleTests {

    @Test
    fun testProductServiceGreeting() {
        val greeting = productService.getGreeting()
        assertTrue(greeting.contains("Product Module"))
    }
}

For the OrderService test, since it depends on the product module, you need to set the extraIncludes parameter in the @ApplicationModuleTest annotation to include it as shown below:

package com.example.springmonolith.order

import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.modulith.test.ApplicationModuleTest
import org.springframework.test.context.junit.jupiter.SpringJUnitConfig
import kotlin.test.assertTrue

@ApplicationModuleTest(extraIncludes = ["product"])
@SpringJUnitConfig
class OrderModuleTests {

    @Autowired
    private lateinit var orderService: OrderService

    @Test
    fun testOrderServiceGreeting() {
        val greeting = orderService.getGreeting()
        assertTrue(greeting.contains("Order Module"))
    }
}

Observability into Module Interactions

Spring Modulith helps generate developer documentation using the Documenter abstraction. This tool can generate Unified Modeling Language (UML) component diagrams describing the relationship between modules and can also generate a tabular view of the key elements of a module. This code snippet generates an application module component diagram using Documenter:

class DocumentationTests {
    private val modules = ApplicationModules.of(SpringmonolithApplication::class.java)

    @Test
    fun writeDocumentationSnippets() {
        Documenter(modules)
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml()
    }
}

Spring Modulith also integrates with Micrometer to capture spans for module interactions. These spans can be sent to tracing tools such as Zipkin to generate runtime visualizations, making it easier to inspect which modules depend on each other, see how events flow across modules, and monitor interactions in production.

Deciding When to Use a Modular Monolith

Although a modular monolith can be the ideal balance between simplicity and structure in many cases, it isn't universally the right choice.

A modular monolith makes sense for:

Early-stage development or limited resources: In the early stages of a product or when working with small teams, a modular monolith reduces operational overhead. Developers can focus on delivering features quickly without the complexity of distributed systems. The modular design still enforces boundaries between business capabilities, so if the system grows, you can gradually migrate high-demand modules into separate microservices.
- Example: A food delivery platform can start with modules for restaurants, menu, and orders inside a single deployable unit, but it can later extract and deploy one of the modules as a microservice.
Complex business domains: Applications that involve complex business logic, workflows, or dependencies can benefit from a modular structure. By encapsulating each business capability in its own module, the system becomes easier to develop, test, and maintain.
- Example: An insurance platform can split policy management, claims processing, and customer support into separate modules to avoid creating interdependencies that can become difficult to maintain.

But a modular monolith may not be the right choice for:

Systems with independent scaling needs: Some systems have uneven load patterns where certain components handle millions of requests daily, while others are rarely used. Because modular monoliths deploy as one unit, you can't scale individual parts independently. A microservice-based approach can more easily scale components that expect a higher load than others.
- Example: In an e-commerce platform, the product catalog or recommendation services may experience higher request volumes than order or payment services.
Systems that use diverse tech stacks: In some organizations, different teams rely on different programming languages, runtimes, or specialized infrastructure for different parts of the system. A modular monolith requires the entire application to use the same stack, which can limit flexibility. In these cases, a microservice-based architecture can provide the isolation needed to mix and match technologies.
- Example: Machine learning or analytics teams may want to use Python or Go for their services, while client-facing or internal services can be based on Kotlin or Java.

Conclusion

Modular monolith architecture allows you to split the application logic into isolated modules with their own business logic, while still being deployed as a single artifact. It combines the benefits of a modular design while maintaining the development and release-related benefits of a monolithic architecture. Additionally, modern programming languages such as Kotlin provide tools that can help you achieve monolith stability without giving up the productivity that draws people to microservices.

Spring Modulith and Kotlin provide the tools to design and enforce clear module boundaries, test modules independently, and monitor their interactions. Try out Spring Modulith to build modular Kotlin applications, while keeping the flexibility to evolve into microservices if your scaling needs change.

Closing the Audit Gap in Human-to-Agent Delegation

Vivek Maskara — Fri, 09 Oct 2026 18:22:49 +0000

When AI agents act on behalf of users, traditional audit logs often don't tell the full story of who actually performed an action. In this article, I explore how to close that gap using Auth0's monitoring, Token Vault, and CIBA approval flows. I also cover how to track delegated actions, manage tokens securely, and maintain a clear audit trail across agent workflows.

AI agents create a new kind of audit gap. When agents act on behalf of a user, they may use tokens issued under that user’s identity, even though the action is executed by the agent. When a high-privilege action shows up in your logs, you need to know whether it came from a human developer, a scheduled backend job, or an AI agent acting with delegated authority. If you only look at traditional audit logs, it can appear that user X did Y, even when the action was carried out indirectly by an agent.

Auditing and traceability get harder as agents operate across identity providers, SaaS platforms, and internal services. A single user request can turn into a chain of delegated actions where intent, authorization, and execution happen in different places. Closing the audit gap means capturing not only what happened, but also who initiated it, how delegation occurred, what permission was used, and what approvals happened along the way.

In this article, you will learn how to use Auth0’s monitoring and logs to capture agent-related activity, how to interpret event types in delegated authorization flows, and how to assemble a practical workflow using Auth0’s built-in monitoring features, logs, and log streams.

Understanding the Audit Gap in AI Agent Systems

Identity models are typically built around a simple flow. A human authenticates, their application receives a token, and calls an API. Even service-to-service calls are usually modeled as explicit machine identities with clear boundaries and predictable lifecycles.

Agentic systems use a similar authentication and authorization model, but the operational context around that delegation changes. You still have a human identity, but you also have an agent that can act for that human, often across multiple external providers. The delegation chain can include a UI action, a background job, a token exchange, and a series of API calls. Many logging pipelines do not represent those handoffs clearly.

The core problem is indirect execution. Attribution gets harder because the actor that initiated intent (the human) and the actor that executed the call (the agent) may not share a runtime, IP, device, or even the same system. For example, when a user asks an agent to pull the latest pipeline from Salesforce and summarize it. The agent would use the stored OAuth 2.0 tokens to call Salesforce APIs. Without explicit delegation context, the audit trail can make the action look like normal user access, even when it was performed by an agent acting on the user’s behalf. For agents, that distinction matters because they may act on a user’s authorization across background workflows, not just in response to a direct click.

Auth0 monitoring and tenant logs help by providing a consistent identity-layer record of authentication, authorization, and delegation-related events. You can correlate token issuance, exchanges, approvals, failures, and downstream activity. Auth0 helps ensure the delegation layer emits enough signals to reconstruct who authorized what, how the agent obtained the ability to do it, and which workflow used that access.

For example, if an agent accesses Google Drive on behalf of a user, you should be able to correlate the user’s original connection to Google, the scopes granted, the token access or refresh event, the agent run ID, and the downstream file access. If the same agent later accesses Salesforce, you should be able to perform the same reconstruction across a different provider. This correlation is what turns disconnected logs into an audit trail.

Monitoring Agent-Driven API Access with Token Vault

Token Vault is designed for applications (and agents) that call external providers like Google or Salesforce on behalf of users. Instead of storing long-lived third‑party refresh tokens in your agent’s database, Token Vault stores provider access and refresh tokens and brokers access to them. Your agent retrieves what it needs at run time to call external APIs under the user’s delegated authorization. This matters because external provider tokens are often the bridge between user intent and agent execution. If every team stores provider refresh tokens in its own service, you quickly lose centralized visibility. You also increase the number of places where sensitive credentials can leak, be misused, or be refreshed without a clear audit trail. Token Vault reduces that sprawl by making token storage and access part of the identity layer, as shown in the diagram below.

When the user first authorizes access to an external provider, Auth0 stores those provider tokens in Token Vault. When the agent later needs to act on the user’s behalf, it retrieves the required token through Auth0. It then uses that token to call the provider API without storing long-lived credentials in the agent backend.

A token vault enables end-to-end audit trails and traceability. Some of its advantages include:

Reduces token sprawl: Centralized storage narrows the number of places where token issuance, refresh, and retrieval can occur.
Helps maintain user context: The agent can act “as the user” without shared service credentials that erase attribution. This does not fully solve the audit gap, but it keeps delegation anchored to a user grant.
Supports asynchronous work without weakening controls: Users authorize once. Agents can operate later. You can still enforce scope and lifecycle controls centrally.
Improves investigation quality: During an incident, investigators can ask which connected account was used, which scopes were available, when the token was accessed, and which agent workflow was running at the time.

Consider a scenario where you are building an agent that can draft a customer follow-up email by pulling context from Google Drive and Salesforce. The user authorizes the required providers once. Later, the agent runs in the background, retrieves the relevant access tokens, reads a document from Google Drive, checks customer details in Salesforce, and drafts a response. With Token Vault in the middle, you will see identity-layer logs worth monitoring:

When the user first connects Google (initial consent and token storage).
When an access token is retrieved for an agent-run task.
When a refresh occurs because the access token has expired.
When scopes change (for example, the agent now needs additional permissions).

If an agent claims it needed Google Drive access, you should see a corresponding event around the same time. If you see repeated refreshes for Google OAuth tokens at unusual hours, that can indicate a loop, an overly broad integration, or a compromised workflow.

Monitoring Approvals in Async Authorization Flows with CIBA

CIBA (Client-Initiated Backchannel Authentication) is a decoupled OAuth/OIDC flow. It lets a client application initiate an authentication or authorization request without the user being present in the same browser session. This fits agent workflows where the agent wants to do something sensitive, but you still want a human approval step before it proceeds. The following diagram shows the CIBA flow in detail:

As shown above, initially, the agent backend sends a backchannel authorization request to Auth0 with the requested scope, binding, and user hint. Auth0 then prompts the user for approval. If approved, the agent receives a token and calls the protected API, while denied or expired requests return an error instead.

CIBA creates explicit, loggable checkpoints in the delegation chain. In a typical “agent just runs” model, you may only see downstream API calls and a token refresh. With CIBA, you can monitor:

When an agent initiated an authorization request: This is an “agent intent” signal that the agent attempted to obtain permission to proceed.
Whether the user approved, denied, or the flow failed/expired: This becomes a clean audit artifact for compliance and incident response.

CIBA fits best when you want agent productivity without silent escalation. For example, if your agent wants to download a customer list from Salesforce and attach it to an internal ticket. Instead of letting the agent use existing tokens silently, you require a CIBA approval with the “export customers” scope.

The agent backend initiates the request.
The user receives a push notification on their phone.
The agent only receives a token that allows the export after approval.
If the request is denied or times out, the agent can fall back to asking the user for a different approach.

To close the audit gap, treat these CIBA events as first-class monitoring signals. In Auth0 logs, look for the sequence of request initiated > pending > approved/denied/expired. Correlate that sequence to token issuance and API activity. Attach a stable correlation ID (agent run ID, job ID, or workflow ID) to the CIBA initiation. Propagate it through internal logs so you can tie “approval granted” to “action executed”. Additionally, you should also decide which actions require CIBA approval. Not every agent action needs a human checkpoint. Reading a calendar to schedule a meeting may be low risk if the user has already granted the right scope. Exporting customer data, sending money, modifying permissions, deleting files, or publishing content may require explicit approval. The goal is to apply approvals where they create meaningful accountability, not to slow every workflow down.

How To Make Delegated Actions Traceable

When working with AI agents, you can do the following to help make delegated actions traceable across identity, application, and provider layers:

Capture identity-layer events in Auth0: Use Auth0 tenant logs to track authentication, authorization, and delegation-related activity via logs.
Centralize external provider tokens: Use Token Vault so token storage, refresh, and retrieval are observable in one place.
Add explicit approvals for sensitive actions: Use CIBA when you need a clear “approved/denied” checkpoint.
Stream logs to your analysis platform: Use log streams to forward Auth0 events to your SIEM (Security Information and Event Management) or data platform.
Propagate correlation IDs end-to-end: Use a stable ID (agent run ID, job ID, workflow ID) across Auth0 initiation, backend execution, and provider API calls.

Auth0 Monitoring Closes the Agent Audit Gap

AI agents create a traceability problem when delegated actions are logged as simple user activity. In third-party integrations, and especially for agentic clients, you need to preserve the difference between the human who authorized access and the system that used it. During an incident, that context helps you answer who authorized the action, which agent or workflow executed it, how access was obtained, and whether a human approved it.

Auth0 provides building blocks to monitor delegated flows at the identity layer. Use monitoring and tenant logs to observe authentication and authorization events. Use Token Vault to centralize external provider tokens used by agents. Use CIBA to add explicit human approvals to asynchronous workflows. With log streams, you can push those events into your data platform and correlate them with application traces and downstream provider audit logs.

Build your agent features so token retrieval, refresh, and approval checkpoints are observable and tied together with correlation IDs. That is the most reliable way to close the audit gap without slowing down developers or agents. Explore Auth0 monitoring and logs today to enhance your visibility and control over agent-driven activities.

Radio: A Shared Channel for my AI Agents

Vivek Maskara — Wed, 16 Sep 2026 00:40:19 +0000

Radio is similar to a Slack workspace but for AI agents. It gives agents a shared channel where they can talk to each other (and humans) to collaborate on a particular feature or project. This shared channel allows agents from different providers to communicate, split work, and utilize each agent's best capabilities. In my daily work, i mostly use Claude code for all UX related work and ChatGPT for all other coding work and currently the handoff process between agents is manual, ie. i ask the agent to write a markdown doc that the other agent could pick up.

With Radio, i can imagine Claude and ChatGPT collaborate on a feature end to end without losing context. If either agents have questions about certain decisions, or architecture choices, they could clarify that directly without making assumptions. Another workflow, where this would help me immensely is: doing work that requires computer use. GPT Astra is great at computer use, and currently i ask Claude code to prep up a prompt with details about what actions need to be performed. But with Radio, i can imagine all of that being streamlined.

Most work now involves more than one agent, often from different providers. One writes the code while another tests it. One runs on your laptop while another runs in the cloud. But the agents can't talk to each other. Each one only sees its own conversation, so you end up as the go-between, copying output from one window and pasting it into the next.

We built Radio to solve this problem. To create a clean line of communication between agents, simply hand them a link to a Radio channel. The agents join the channel and talk to each other, and to you, in real time.

Radio works with any agent that can fetch a URL, so Claude Code, Codex, Cursor, OpenCode, and Grok all join the same way. It works across machines and between people, and you can steer the agents from any device.

Create a channel at radio.plasma.ai
Copy the link
Paste into one or more agents
The agents join the channel. Send one message and they take it from there, replying to you and to each other
The simplest way to think about a Radio channel is as a meeting. Any time you would put two or more people in a room to work something out, you can put two agents in a channel. There are three kinds, and each one builds on the last.

Team meeting: All the agents on your computer in one channel. One agent writes the code while another tests it. Review a PR together, split up a task, debate a bug. Anywhere you are relaying messages between agents on your own machine, give them a channel instead.
Cross-functional meeting: Agents in different places: your laptop, a cloud agent, a teammate's machine. Their Claude talks to your Claude, Codex, Grok, etc. The channel is the shared surface, so nobody has to be the go-between.
External meeting: Everything above, now multiplayer. Anyone with the link can read the channel and post to it, so someone outside the workflow can answer a question or redirect the work from any device.
In every case, the channel is also the record. Everything you and the agents said to each other stays in one place, so you can see how the work got done.

Radio is a core primitive of our first product, Fractal.

Fractal lets a team delegate real work to agents the way it would to people: pick the right model for each job, hand it a goal and a budget, and watch the work happen in real time.

You can see other building blocks of Fractal on our Research page.

Fractal is coming to the cloud. See the tree, steer its nodes, and track costs as the work runs.

Early access opens soon.

Why Google’s Open Knowledge Format Matters for Developers and Content Creators?

Vivek Maskara — Wed, 17 Jun 2026 02:24:11 +0000

Most teams don’t suffer from a lack of data. They suffer from a lack of shared context. Definitions, caveats, ownership, and “how to use this safely” guidance end up scattered across wikis, tickets, dashboards, and people’s heads. Google’s Open Knowledge Format (OKF) tackles that sprawl by packaging curated context as a portable, versionable bundle of “just files” that both humans and AI agents can consume reliably (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).

This article covers the problem OKF targets, what the format is (and isn’t), and the building blocks that make it work. It then explains why OKF fits developer workflows and content operations, plus adoption patterns, tradeoffs, and practical next steps.

The real problem OKF is trying to solve: “context sprawl”

OKF exists because the most important knowledge in an organization often isn’t the data itself. It’s the context around the data, and that context is scattered. Google describes this as “metadata, context, and curated knowledge” spread across too many surfaces to share or reuse cleanly (Google Cloud Blog, Jun 12 2026).

This fragmentation hurts humans. It hurts AI agents and cross-team work even more. People compensate with experience. They know which wiki is “more correct,” who to ask, and which dashboard is legacy. Agents don’t have that intuition. When context is missing or split across systems, an agent has to infer and guess. That leads to confident wrong answers and brittle automations.

It also helps to separate data from context:

Data: table schemas, API contracts, dbt models.
Context: metric definitions, caveats, ownership, join guidance, deprecations, and runbooks.

Without context, two teams can query the same table and still disagree on what “revenue” means.

Before OKF, a developer debugging a revenue discrepancy might find SQL in a dashboard, a definition in a wiki page, and a deprecation note buried in a ticket. Then they repeat the same archaeology next week. OKF is positioned as a portable corpus that tools (and agents) can consume, not as “another portal.”

What OKF is (and what it is not)

The simplest way to understand OKF is as a file-based packaging standard for curated knowledge. It’s small enough to live in git, structured enough to index, and neutral enough to move across tools.

OKF in one sentence: a directory of Markdown + YAML frontmatter

Per Google’s announcement and the specification, OKF is a vendor-neutral way to package curated organizational knowledge as a directory of Markdown files. Each file includes YAML frontmatter for structured metadata (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). The key idea is that it’s “just files.” There’s no required SDK, runtime, schema registry, or central service.

Markdown plus YAML is a deliberate trade. Humans can review it in pull requests, and diffs stay readable. Tools can parse the frontmatter to index and retrieve concepts consistently.

---
type: metric
title: "Revenue (Net)"
description: "Net revenue excluding refunds and chargebacks."
resource: bigquery://analytics.metrics/revenue_net
tags: [finance, gaap, executive-dashboard]
timestamp: 2026-06-12T00:00:00Z
---
Metric notes, caveats, and links go here in Markdown.

What OKF is not: not a replacement for domain schemas or APIs

The spec is explicit that OKF doesn’t replace domain-specific schemas or interface definitions such as Avro, Protobuf, OpenAPI, or dbt models (OKF SPEC.md). Instead, it acts as a curation and metadata wrapper. It points at sources of truth and adds context they don’t capture well, like usage guidance and operational notes. This reduces schema duplication and helps avoid “two sources of truth.”

---
type: api-endpoint
title: POST /v1/orders
resource: https://api.example.com/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Use `Idempotency-Key` for retries. Deprecated fields: `promoCode` (use `discounts[]`).

Common confusion: OKF vs Google Knowledge Graph / schema.org markup

OKF is for internal, file-based knowledge bundles meant to be shared and used by tools and agents. The Google Knowledge Graph Search API is different. It’s a hosted service that returns entity results as JSON-LD using schema.org types (Knowledge Graph Search API docs). A quick check helps: OKF lives in repos and filesystems. Knowledge Graph is an online entity search API.

How OKF works: the building blocks developers can reason about

Once you accept “it’s just files,” the next question is how those files become something tools can index, link, and retrieve. OKF’s answer is a small set of filesystem-friendly rules.

Knowledge Bundles, Concepts, and Concept IDs

The spec defines a filesystem-native mental model (OKF SPEC.md):

A Knowledge Bundle is a distributable directory tree.
Each Concept is exactly one Markdown document.
The Concept ID is derived from the file path (minus .md).

Path-based IDs stay stable under version control. They also make it easy for tools to reference concepts without inventing a separate identifier scheme.

knowledge-bundle/
  datasets/
    ga4_ecommerce.md            # conceptId: datasets/ga4_ecommerce
  tables/
    ga4/events.md               # conceptId: tables/ga4/events
  metrics/
    revenue_net.md              # conceptId: metrics/revenue_net
  runbooks/
    revenue_discrepancy.md      # conceptId: runbooks/revenue_discrepancy

YAML frontmatter as the “queryable surface area”

OKF keeps structure intentionally small. Google highlights a compact set of frontmatter fields, type, title, description, resource, tags, timestamp, that tools can index for filtering and routing (Google Cloud Blog, Jun 12 2026). The spec defines the normative rules (OKF SPEC.md).

This is what makes “retrieve all runbooks tagged incident-response” a metadata query instead of a full-text guessing game.

---
type: metric
title: Revenue (Net)
description: Net revenue excluding refunds and chargebacks.
resource: bigquery://analytics.metrics/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---

Markdown body as the “human-first, agent-usable” narrative layer

OKF uses plain Markdown for the body. That keeps content readable in GitHub or internal doc sites. It also stays easy for agents to chunk, quote, and follow links. Links express relationships beyond folders. For example, a metric can point to its source table and the runbook for incidents.

See source table: ../tables/ga4/events.md
Incident response: ../runbooks/revenue_discrepancy.md

Why OKF matters for developers: interoperability, workflows, and agent grounding

With the mechanics in place, the developer value becomes clearer. OKF is a low-friction interchange format that fits engineering workflows while making agent grounding more dependable.

Interoperability without glue code: “format, not service”

OKF matters to developers because it’s a format you can move around, not a platform you must integrate with. Bundles are “just files,” so producers and consumers only need filesystem access plus a Markdown/YAML parser (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). You can keep a bundle in git, publish a pinned tarball for reproducible runs, or mount it into an environment where tools and agents can read it.

A concrete payoff is cross-stack reuse. A data platform team can publish a bundle once. Then a Python agent pipeline, a TypeScript IDE helper, and a catalog ingestion job can all consume the same directory tree.

“Knowledge as code” practices applied to context

Because OKF is diffable text, it fits normal engineering discipline. Metric definitions and runbooks can be updated via PRs, reviewed by owners, and rolled back when needed. That turns “why did this number change?” into a git blame instead of a Slack archaeology expedition. The spec’s version-control friendliness is the enabling detail (OKF SPEC.md).

In practice, teams add CI gates that keep the bundle coherent:

# Example CI gate: fail if any concept link points to a missing file
python scripts/check_links.py knowledge-bundle

Better agent grounding: fewer hallucinations, more reliable automation

Google frames OKF as a way to ground agents with the right context. That includes definitions, caveats, deprecations, and operational procedures (Google Cloud Blog, Jun 12 2026). Stable concept IDs plus queryable frontmatter let retrieval start narrow (by type and tags). Tools can then traverse links to assemble the “full story” for a task.

---
type: runbook
title: Revenue discrepancy triage
tags: [incident-response, revenue]
timestamp: 2026-06-12T00:00:00Z
---

An incident bot can pull the runbook and route to the right owner. An analytics agent can retrieve the metric concept to avoid using the wrong definition.

Why OKF matters for content creators: an “LLM-wiki” you can ship

Developers care about interoperability and workflow fit. Content creators care about portability, editorial control, and reuse across audiences and tools. OKF is designed to meet those needs without forcing a single publishing platform.

OKF as a standardized, portable “LLM-wiki” pattern

OKF turns the “LLM-wiki” idea into something teams can adopt without committing to one wiki product. Google frames the format as a way to standardize that pattern: write human-readable Markdown, add a small amount of structured metadata, and ship the result as a bundle of files (Google Cloud Blog, Jun 12 2026).

That portability is the unlock. A docs team can curate a product-concepts/ bundle for feature behavior and deprecations. A data team can curate an analytics-concepts/ bundle for metrics, tables, and runbooks. You can publish both internally, open-source a subset, or share across org boundaries.

Metadata that makes content discoverable and reusable

YAML frontmatter is what makes OKF feel less like “a folder of docs” and more like a queryable knowledge base. Tags let you slice content by audience or lifecycle (deprecated, oncall, exec). resource anchors a concept to the system of record. timestamp provides a freshness signal that search and agents can respect.

Over time, editors can standardize templates per type, so readers recognize the shape quickly.

---
type: runbook
title: Payments latency spike
description: Triage and mitigation steps for elevated p95 latency.
resource: https://monitoring.example.com/dashboards/payments
tags: [incident-response, payments, oncall]
timestamp: 2026-06-12T00:00:00Z
---

## Symptoms
## Diagnosis
## Mitigation
## Escalation

Publishing and maintenance workflows that don’t fight your tools

Because OKF uses Markdown, it renders cleanly on GitHub/GitLab. It can also sync into an internal docs portal without rewriting content. Google highlights shipping bundles as artifacts, which maps well to editorial release trains (Google Cloud Blog, Jun 12 2026). For example, you can run a monthly “data platform bundle” release with changelogs, review rotations, and a style guide.

Practical adoption patterns

OKF is simple in theory. Adoption succeeds when you use that simplicity to enforce clarity, not to create near-duplicate docs.

Pattern: concept-per-file bundles organized by domain

The spec’s “concept-per-file” rule is easiest to run when you organize by domain folders. Express relationships as links rather than mega-pages (OKF SPEC.md). A simple starting tree keeps concepts small enough to reuse.

knowledge-bundle/
  metrics/revenue_net.md
  tables/orders.md
  policies/refunds.md
  runbooks/revenue_discrepancy.md

Inside metrics/revenue_net.md, keep the YAML frontmatter queryable. Use Markdown links to connect the graph:

---
type: metric
title: Revenue (Net)
resource: bigquery://analytics.marts/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---

Derived from [Orders table](../tables/orders.md). Refund handling: [Refund policy](../policies/refunds.md).

Pattern: distribute OKF as an artifact (repo, release, filesystem)

Because bundles are “just files,” distribution is a packaging decision. Use a git repo for collaboration and review. Publish tarball releases for pinned, reproducible consumption. Optionally sync to a shared mount for runtime access (Google Cloud Blog, Jun 12 2026).

For agents, pin explicitly, for example: “use bundle v2026.06 for this workflow run.” That prevents retrieval from drifting mid-incident.

tar -czf knowledge-bundle.tgz knowledge-bundle/
# attach knowledge-bundle.tgz to a release like v2026.06

Pattern: pair OKF with catalog ingestion (Google Cloud Knowledge Catalog example)

Google says Google Cloud Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026). This split is useful. OKF stays the interchange layer. Catalogs become optional UX and indexing layers, not the only home for context.

For more background on the product direction, see Google’s Knowledge Catalog introduction (Knowledge Catalog blog, Apr 22 2026).

Tradeoffs and pitfalls: where teams stumble and how to avoid it

OKF is intentionally minimal, which makes it portable. The work doesn’t disappear. It shifts into conventions and maintenance.

Inconsistent conventions reduce interoperability

Minimal structure is also a sharp edge. If every team invents its own type values, tag styles, and linking habits, cross-bundle queryability drops. That undermines the standardization OKF is meant to enable (OKF SPEC.md).

Treat conventions as part of the product:

Define a shared type taxonomy.
Use a controlled tag vocabulary (including casing).
Require consistent Markdown sections per type.
Standardize link patterns (relative links, concept-per-file).

A common failure mode is tag casing drift. One team writes incident-response, another writes IncidentResponse, and filters miss half the runbooks. Fix it with templates, review checklists, and CI that rejects nonconforming metadata.

# scripts/normalize_tags.py
import sys, pathlib, re, yaml

def load_frontmatter(text: str):
  m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
  return (yaml.safe_load(m.group(1)) or {}) if m else {}

root = pathlib.Path(sys.argv[1])
bad = []
for md in root.rglob("*.md"):
  fm = load_frontmatter(md.read_text(encoding="utf-8"))
  tags = fm.get("tags") or []
  if any(t != t.lower() for t in tags):
    bad.append(str(md))
if bad:
  raise SystemExit("Non-lowercase tags in:\n" + "\n".join(bad))

Treating OKF as the system of record for schemas

OKF does not replace domain schemas like Avro, Protobuf, or OpenAPI (OKF SPEC.md). Use it to explain and operationalize them. Keep it focused on rationale, caveats, examples, deprecations, and safe usage guidance. A simple rule helps: resource must point to the canonical source-of-truth location.

---
type: api-endpoint
title: CreateOrder
resource: https://repo.example.com/apis/orders/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Retries require `Idempotency-Key`. `promoCode` is deprecated; use `discounts[]`.

Stale knowledge and missing freshness signals

Bundles rot unless you operationalize freshness. Google calls out timestamp as part of the structured fields (Google Cloud Blog, Jun 12 2026). Use it to power staleness dashboards and enforcement, especially for runbooks.

Add ownership conventions, review SLAs, and automated reminders. For high-risk concepts, add a “Last verified” line in Markdown.

# Fail CI if any incident runbook is older than 90 days
python scripts/check_staleness.py knowledge-bundle --type runbook --tag incident-response --max-age-days 90

How to get started: next steps for developers and content teams

Treat OKF like any shared interface. Start with a small, high-value surface area. Lock down conventions early. Add enough automation to keep the bundle trustworthy.

1. Start small: pick one high-value domain and define conventions

Start where missing context repeatedly burns time. Good candidates include your top executive metrics, the most-queried tables, or on-call runbooks. Keep the first bundle small. Prove the workflow (author → review → publish → consume) before scaling.

Define conventions up front:

A minimal type list you will actually use (for example metric, table, runbook, dataset)
A tag vocabulary with consistent casing
One Markdown template per type

Google points to sample bundles (GA4 e-commerce, Stack Overflow, Bitcoin) in its announcement. Keep the spec open while you implement so you follow the normative rules (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).

2. Add quality gates: validation, link checks, and publishing

Because OKF requires no tooling, you can add lightweight CI checks that match your conventions. Common gates include required frontmatter fields, forbidden tags, and broken relative links. If you want stricter guarantees, add JSON Schema validation.

A simple first gate is ensuring Concept IDs (path minus .md) are unique and indexable:

# scripts/index_concepts.py
import sys, pathlib

root = pathlib.Path(sys.argv[1])
ids, dupes = set(), []
for md in root.rglob("*.md"):
    cid = md.relative_to(root).with_suffix("").as_posix()
    if cid in ids:
        dupes.append(cid)
    ids.add(cid)

if dupes:
    raise SystemExit("Duplicate concept IDs:\n" + "\n".join(dupes))
print(f"Indexed {len(ids)} concepts")

Publish in two forms: rendered docs (GitHub Pages or an internal portal) and a pinned bundle artifact (release tarball) for agents.

3. Decide how agents will consume it

Plan for multiple consumption modes without changing content. Options include direct filesystem reads, an indexing pipeline for RAG, or catalog ingestion. Google notes that Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026).

A practical retrieval strategy is “filter, then traverse”:

Filter by type and tags (for example, type: dataset plus a domain tag).
Follow links dataset → tables → metrics → runbooks.

OKF’s core promise is durability. Once your context lives in a knowledge bundle with consistent metadata and links, you can switch catalogs, search layers, and agent frameworks without rewriting the knowledge itself.

You’re Already Using Git Worktrees. You Should Understand Them.

Vivek Maskara — Mon, 18 May 2026 12:18:41 +0000

If you’ve ever run git clone and then started editing files in the resulting folder, you’ve been using a Git worktree all along. Git just doesn’t call it that in day-to-day conversation.

git worktree is the feature that lets you add more checkouts (more folders with files on disk) that all share the same underlying repository history. Done well, it replaces the “stash/switch/stash-back” dance with something simpler: keep your in-progress work open in one directory, and do the urgent/clean/experimental thing in another.

This is a mental-model article: what a worktree is, why Git enforces “one branch per worktree,” and the few lifecycle commands that keep worktrees from turning into confusing “already checked out” / stale-metadata problems.

The Mental Model: Shared History, Separate Working State

Git’s own git worktree docs describe the feature as managing “multiple working trees attached to the same repository.” The twist is that you always start with one: the directory you land in after a normal (non-bare) clone is the main worktree.

Linked worktrees are additional working directories attached to the same repo. They share the object database (commits/trees/blobs), but each worktree has its own working state: checked-out files, its own HEAD, and its own index (staging area).

That’s the whole trick:

Shared: history and objects (you don’t redownload Git data like a second clone).
Per worktree: files-on-disk + HEAD + index (you don’t stomp on your other checkout).

One nuance that matters: a worktree isn’t its own independent “repo.” Most refs and remote configuration are shared. When you git fetch, you’re updating the shared repository data that all worktrees see. That’s what makes worktrees lighter than multiple clones—but it’s also why Git has to be careful about how a branch name maps to a checkout.

If you want a deeper explanation of why “objects live once” makes this efficient, the Git book’s “Git Objects” chapter is a good reference: Git Internals: Git Objects.

What Actually Changes on Disk when You Add a Worktree

Git keeps the shared repository database in one place, then tracks per-worktree state separately. That’s why it can add a second checkout without cloning.

If you’ve ever noticed that .git sometimes looks like a file (not a folder), that’s often Git pointing your working tree at the real “gitdir.” Worktrees lean on this idea heavily: each worktree has its own admin area, but the objects are shared.

The Rule that Surprises People: One Branch per Worktree

If you try to attach the same branch to two worktrees, Git will usually refuse with “branch is already checked out.” That refusal is protection.

The core reason is that a branch name is just a movable pointer. If two working directories could both “be” feature, the branch pointer could move in one directory while the other directory still has older files on disk. Now you have a branch name that no longer uniquely identifies a single working state.

Said differently: Git is fine with multiple worktrees having different HEADs (each checkout is independent), but a branch ref like refs/heads/feature is shared at the repository level. Letting two worktrees both “own” the same branch would create a footgun where “what commit is feature?” depends on which folder last advanced it.

When you want “two directories, same starting point,” Git’s safer options are:

Create a new branch name for the second worktree:

git worktree add ../wt-fix -b fix-branch

Use a detached HEAD when you don’t intend to keep the work long-term:

git worktree add -d ../wt-scratch

Detached HEAD is the “I want another directory at this commit, but I’m not claiming a branch name” mode. That’s why it’s safe: you can still make commits, but you’re not advancing a shared branch ref unless you later create one.

--force exists for edge cases, but it’s opting out of a guardrail. If you don’t already know why you need it, you probably don’t.

Where Worktrees Shine (in Practice)

Worktrees are a productivity primitive whenever parallelism beats context switching. Three common patterns:

1) Hotfix without Touching Your In-Progress Directory

When a production issue lands mid-feature, create a new worktree on a hotfix branch:

git worktree add ../wt-hotfix -b hotfix

You get a clean checkout in a new folder, and your original directory stays exactly as it was. When you’re done, remove it cleanly:

git worktree remove ../wt-hotfix

Tower’s Git worktree FAQ describes this as one of the “default” worktree use cases, and it’s the one most people feel immediately.

2) PR Reviews and Repros in a Clean Sandbox

You can attach a worktree directly to a remote-tracking branch and keep it around for as long as the review takes:

git worktree add ../wt-review origin/some-pr-branch

3) Scratch Experiments You Don’t Want to Keep

Detached worktrees are great for “let me try something” work without committing to a branch name yet:

git worktree add -d ../wt-scratch

If you end up making commits you want to keep, create a branch before you delete the folder so you don’t lose track of them.

A Quick Note on “Why Not Just Clone Twice?”

Separate clones can absolutely solve the same “two directories” problem. The difference is mainly cost and coupling:

Clones duplicate setup (another fetch/clone, another .git object store).
Worktrees share Git objects, but still behave like separate checkouts.

If you need complete isolation (different remotes, radically different Git config, or you want to move one copy around freely), a second clone can still be the simplest answer.

Keeping Your Directories Sane

The simplest convention (and the one that avoids the “oops, I edited the wrong checkout” mistake) is: keep linked worktrees outside the main project folder.

repo/            # main worktree
repo-hotfix/     # linked worktree
repo-review/     # linked worktree

If you do this often, encode intent in the directory name so it’s searchable later (wt-hotfix-1234, wt-pr-998, wt-bisect-crash) instead of generic tmp/.

If you want all worktrees contained under one parent folder, a popular layout is “bare repo + many worktrees” (see Nick Nisi and Ahmed El Gabri). For background on bare repositories themselves, the Git book chapter is a good reference: Git Basics: Getting a Git Repository.

If you try the “bare repo + worktrees” approach, keep the tradeoff in mind: you’re saving Git object duplication, not environment duplication. Two worktrees can still mean two node_modules/ folders, two build outputs, and two IDE indexes. If setup dominates your workflow, keep only the worktrees you’re actively using.

The Lifecycle Gotchas (and the 5 Commands that Prevent Them)

Removing vs Deleting (Stale Metadata)

Deleting a worktree folder in Finder isn’t the same as telling Git it’s gone. Prefer:

git worktree remove ../wt-review

If you already deleted the folder, clean up the leftover admin state:

git worktree prune

Git can also garbage-collect stale worktree metadata automatically over time (controlled by gc.worktreePruneExpire). That’s helpful, but it’s not a substitute for removing worktrees intentionally when you’re done.

“This Branch Is Already Checked Out”

This is Git enforcing “one branch per worktree.” Your usual fixes are:

make a new branch name (-b)
use detached HEAD (-d)

If you’re debugging “why won’t Git let me…”, list the current attachments:

git worktree list

Moving Worktrees (and Repairing when Paths Change)

If you need to reorganize, prefer Git’s commands over dragging folders around in your file manager.

git worktree move <worktree> <new-path> relocates a linked worktree (you can’t move the main worktree).
If you moved things manually and links broke, git worktree repair can reestablish the connection in supported cases.

Intermittent Drives: Lock Before Git Prunes

If a worktree lives on an external drive or network mount, Git may treat it as “missing” when the volume isn’t mounted. Use git worktree lock to prevent surprises:

git worktree lock --reason "On external drive" /Volumes/SSD/wt-release

Cheat Sheet

git worktree add ../wt-name -b my-branch   # new worktree + new branch
git worktree add ../wt-name origin/branch  # worktree from remote-tracking branch
git worktree add -d ../wt-scratch          # detached-HEAD scratch worktree
git worktree list                          # see what's attached
git worktree remove ../wt-name             # remove cleanly
git worktree prune                         # cleanup after manual deletion

The Takeaway

Worktrees aren’t a niche add-on. They’re the name for the checkout you already use, plus a way to add more checkouts without cloning again. Keep the mental model in your head—shared history, separate working state—and Git’s guardrails (like one branch per worktree) stop feeling arbitrary and start feeling helpful.

If you learned something from this post, give me a follow and checkout the AI powered markdown editor that i am building on the side.