README
¶
doczel
Documentation automation platform for the Bazel DevSite-to-Mintlify migration. Deterministic MDX repair, tiered validation, autonomous PR creation, and an expanding set of integrations (MCP, A2A, semantic search, studio, voice).
Quick Start
git clone https://github.com/albertocavalcante/doczel.git
cd doczel
just build # -> bin/doczel, bin/zel
Prerequisites: Go 1.26+, just, gh (authenticated).
Setup and first run
doczel init # interactive workspace setup
doczel doctor # verify environment
doczel status ~/forks/bazel-docs --suggest # inspect backlog
doczel fix path/to/file.mdx --dry-run # preview fixes
doczel fix path/to/file.mdx # apply fixes
doczel validate path/to/file.mdx --tier 2 # validate
zel run --repo ~/forks/bazel-docs --dry-run # agent dry run
zel run --repo ~/forks/bazel-docs --batch-size 5
What's In The Box
doczel CLI |
Fix, diff, classify, validate, audit links/anchors, manage workspace |
zel agent |
Batch-process .mintignore, reason through failures, create PRs |
| Server + UI | ConnectRPC backend, Tauri/SvelteKit desktop app |
| Integrations | MCP tools, A2A agent protocol, Slack, Google Docs |
| Extras | Semantic search, studio pipeline, voice control |
Project Status
The CLI/agent migration workflow (doczel fix/diff/validate, zel run/status) is the most mature path. Server, UI, studio, and voice features are functional but evolving.
Development
just build # build both binaries
just test # go test ./...
just lint # go vet ./...
just check # build + test + lint
Documentation
| Doc | What's in it |
|---|---|
| docs/workflows.md | Step-by-step usage for all major workflows |
| docs/architecture.md | Subsystems, fix engine, execution backends, repo layout |
| docs/configuration.md | Config files, YAML examples, environment variables |
| CONTRIBUTING.md | How to contribute |
| ui/README.md | Desktop app setup |
| docs/design/ | Design docs (studio, voice, roadmap) |
External References
| Migration repo | bazel-contrib/bazel-docs |
| Upstream source | bazelbuild/bazel/tree/master/docs |
| Live docs | bazel.build |
| Tracker | bazel-contrib/projects/5 |
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
doczel
command
|
|
|
doczel-server
command
|
|
|
zel
command
|
|
|
gen
|
|
|
internal
|
|
|
a2aclient
Package a2aclient wraps the A2A client SDK for delegating tasks to remote agents.
|
Package a2aclient wraps the A2A client SDK for delegating tasks to remote agents. |
|
a2aserver
Package a2aserver exposes zel as an A2A (Agent-to-Agent) protocol server.
|
Package a2aserver exposes zel as an A2A (Agent-to-Agent) protocol server. |
|
acpagent
Package acpagent implements an ACP (Agent Client Protocol) agent that allows ACP-compatible editors (Zed, JetBrains, Neovim) to use zel as an autonomous coding agent for Bazel documentation migration.
|
Package acpagent implements an ACP (Agent Client Protocol) agent that allows ACP-compatible editors (Zed, JetBrains, Neovim) to use zel as an autonomous coding agent for Bazel documentation migration. |
|
actrunner
Package actrunner provides a Go wrapper around nektos/act for running GitHub Actions workflows locally.
|
Package actrunner provides a Go wrapper around nektos/act for running GitHub Actions workflows locally. |
|
agent/durable
Package durable provides DBOS-inspired idempotent step execution backed by SQL.
|
Package durable provides DBOS-inspired idempotent step execution backed by SQL. |
|
agent/executor
Package executor abstracts command execution and file I/O for the zel agent, allowing commands to run locally, in Docker containers, Linux sandboxes (bubblewrap, nsjail), or cloud environments (Daytona, E2B).
|
Package executor abstracts command execution and file I/O for the zel agent, allowing commands to run locally, in Docker containers, Linux sandboxes (bubblewrap, nsjail), or cloud environments (Daytona, E2B). |
|
agent/roles
Package roles provides a multi-agent orchestration framework where specialized agents (Planner, Executor, Reviewer) collaborate via a common Role interface.
|
Package roles provides a multi-agent orchestration framework where specialized agents (Planner, Executor, Reviewer) collaborate via a common Role interface. |
|
agent/statestore
Package statestore provides pluggable persistence backends for agent run state.
|
Package statestore provides pluggable persistence backends for agent run state. |
|
agent/toolreg
Package toolreg provides a typed tool registry with JSON Schema validation, structured errors, per-role scoping, and pre/post execution hooks.
|
Package toolreg provides a typed tool registry with JSON Schema validation, structured errors, per-role scoping, and pre/post execution hooks. |
|
audio
Package audio provides interfaces and implementations for microphone capture and audio playback.
|
Package audio provides interfaces and implementations for microphone capture and audio playback. |
|
audit
Package audit provides audit logging for mutating RPC operations.
|
Package audit provides audit logging for mutating RPC operations. |
|
auth
Package auth provides JWT authentication middleware for the doczel server.
|
Package auth provides JWT authentication middleware for the doczel server. |
|
burndown
Package burndown cross-references .mintignore entries with open GitHub PRs to produce a deterministic report: coverage, overlaps, and gaps.
|
Package burndown cross-references .mintignore entries with open GitHub PRs to produce a deterministic report: coverage, overlaps, and gaps. |
|
chat
Package chat provides a conversational AI engine for the doczel desktop app.
|
Package chat provides a conversational AI engine for the doczel desktop app. |
|
cilocal
Package cilocal provides fast, native validation of the bazel-docs CI pipeline steps without requiring Docker or nektos/act.
|
Package cilocal provides fast, native validation of the bazel-docs CI pipeline steps without requiring Docker or nektos/act. |
|
cost
Package cost provides token usage analysis from session journal data.
|
Package cost provides token usage analysis from session journal data. |
|
deepwiki
Package deepwiki provides a typed Go client for the DeepWiki MCP server.
|
Package deepwiki provides a typed Go client for the DeepWiki MCP server. |
|
docs
Package docs provides a tool-agnostic documentation platform abstraction supporting Mintlify and future backends (DevSite, etc.).
|
Package docs provides a tool-agnostic documentation platform abstraction supporting Mintlify and future backends (DevSite, etc.). |
|
extdocs
Package extdocs provides URL builders for external documentation platforms (CodeWiki, DeepWiki) that index Bazel source and documentation repositories.
|
Package extdocs provides URL builders for external documentation platforms (CodeWiki, DeepWiki) that index Bazel source and documentation repositories. |
|
gerrit
Package gerrit provides Gerrit Code Review integration for doczel, bridging the gerrit-sdk with domain-specific types and queries.
|
Package gerrit provides Gerrit Code Review integration for doczel, bridging the gerrit-sdk with domain-specific types and queries. |
|
gitinfo
Package gitinfo provides lightweight git helpers using exec.Command.
|
Package gitinfo provides lightweight git helpers using exec.Command. |
|
keyring
Package keyring provides secure credential storage using the OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) with automatic fallback to environment variables.
|
Package keyring provides secure credential storage using the OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) with automatic fallback to environment variables. |
|
llm
Package llm provides a unified LLM abstraction layer for doczel.
|
Package llm provides a unified LLM abstraction layer for doczel. |
|
log
Package log provides centralized structured logging backed by uber/zap, exposed to application code through the standard log/slog interface.
|
Package log provides centralized structured logging backed by uber/zap, exposed to application code through the standard log/slog interface. |
|
mcpclient
Package mcpclient wraps an MCP client session as a ToolProvider, enabling the zel Reasoner to consume external MCP tools.
|
Package mcpclient wraps an MCP client session as a ToolProvider, enabling the zel Reasoner to consume external MCP tools. |
|
mcpserver
Package mcpserver exposes doczel functionality as an MCP (Model Context Protocol) server.
|
Package mcpserver exposes doczel functionality as an MCP (Model Context Protocol) server. |
|
mdxgen
Package mdxgen builds MDX (Markdown + JSX) content with type-safe, composable nodes.
|
Package mdxgen builds MDX (Markdown + JSX) content with type-safe, composable nodes. |
|
mintlify
Package mintlify provides a typed Go wrapper around the Mintlify (mint) CLI.
|
Package mintlify provides a typed Go wrapper around the Mintlify (mint) CLI. |
|
narrate
Package narrate generates audio narration for documentation pages.
|
Package narrate generates audio narration for documentation pages. |
|
otel
Package otel provides OpenTelemetry setup for the zel agent.
|
Package otel provides OpenTelemetry setup for the zel agent. |
|
pipeline
Package pipeline implements the commit-to-documentation automation pipeline.
|
Package pipeline implements the commit-to-documentation automation pipeline. |
|
prcache
Package prcache provides a persistent, SQLite-backed cache for GitHub pull requests with incremental background syncing and local correlation against burndown, tracking, and agent data.
|
Package prcache provides a persistent, SQLite-backed cache for GitHub pull requests with incremental background syncing and local correlation against burndown, tracking, and agent data. |
|
preview
Package preview manages a Mintlify dev server for live documentation preview.
|
Package preview manages a Mintlify dev server for live documentation preview. |
|
render
Package render provides server-side markdown/MDX rendering.
|
Package render provides server-side markdown/MDX rendering. |
|
render/components
Package components generates custom interactive React/MDX component snippets for Mintlify documentation.
|
Package components generates custom interactive React/MDX component snippets for Mintlify documentation. |
|
rulesdoc
Package rulesdoc provides LLM-based enrichment for rule documentation.
|
Package rulesdoc provides LLM-based enrichment for rule documentation. |
|
scm
Package scm provides a tool-agnostic source control abstraction supporting git, jujutsu (jj), and Git Butler (but).
|
Package scm provides a tool-agnostic source control abstraction supporting git, jujutsu (jj), and Git Butler (but). |
|
skills
Package skills implements the Agent Skills open standard (SKILL.md format) for the zel agent, providing discovery, parsing, security, and tool integration.
|
Package skills implements the Agent Skills open standard (SKILL.md format) for the zel agent, providing discovery, parsing, security, and tool integration. |
|
sqlutil
Package sqlutil provides shared SQLite utilities used across multiple packages.
|
Package sqlutil provides shared SQLite utilities used across multiple packages. |
|
studio
Package studio orchestrates the full MDX-to-MP4 video generation pipeline, combining content analysis, script generation, storyboarding, rendering, and composition into a single automated workflow.
|
Package studio orchestrates the full MDX-to-MP4 video generation pipeline, combining content analysis, script generation, storyboarding, rendering, and composition into a single automated workflow. |
|
trace
Package trace provides commit lineage tracing across the Bazel documentation pipeline: Piper → Gerrit → GitHub → bazel-docs.
|
Package trace provides commit lineage tracing across the Bazel documentation pipeline: Piper → Gerrit → GitHub → bazel-docs. |
|
tracking
Package tracking integrates supplementary tracking data from Google Sheets or CSV files into the burndown pipeline.
|
Package tracking integrates supplementary tracking data from Google Sheets or CSV files into the burndown pipeline. |
|
vectorstore
Package vectorstore provides a vector similarity search layer for doczel.
|
Package vectorstore provides a vector similarity search layer for doczel. |
|
video
Package video provides video generation and composition utilities.
|
Package video provides video generation and composition utilities. |
|
video/remotion
Package remotion provides a CodeAnimator implementation that renders video using the Remotion framework (React-based programmatic video).
|
Package remotion provides a CodeAnimator implementation that renders video using the Remotion framework (React-based programmatic video). |
|
voice
Package voice defines interfaces and types for speech-to-text (STT) and text-to-speech (TTS) providers used by the zel agent's voice control system.
|
Package voice defines interfaces and types for speech-to-text (STT) and text-to-speech (TTS) providers used by the zel agent's voice control system. |
|
voice/deepgram
Package deepgram implements a voice.STT provider using the Deepgram streaming speech-to-text API (Nova-2 model).
|
Package deepgram implements a voice.STT provider using the Deepgram streaming speech-to-text API (Nova-2 model). |
|
voice/dispatch
Package dispatch bridges natural language transcripts to agent actions.
|
Package dispatch bridges natural language transcripts to agent actions. |
|
voice/elevenlabs
Package elevenlabs implements a TTS provider using the ElevenLabs Speech Synthesis API.
|
Package elevenlabs implements a TTS provider using the ElevenLabs Speech Synthesis API. |
|
voice/openaitts
Package openaitts implements a TTS provider using the OpenAI Audio Speech API.
|
Package openaitts implements a TTS provider using the OpenAI Audio Speech API. |
|
voice/say
Package say implements a TTS provider using the macOS built-in say command.
|
Package say implements a TTS provider using the macOS built-in say command. |
|
voice/session
Package session manages voice interaction lifecycles, coordinating microphone capture, STT streaming, agent dispatch, and TTS playback.
|
Package session manages voice interaction lifecycles, coordinating microphone capture, STT streaming, agent dispatch, and TTS playback. |
|
voice/voicetest
Package voicetest provides test doubles for the voice package interfaces.
|
Package voicetest provides test doubles for the voice package interfaces. |
|
wikidiff
Package wikidiff compares DeepWiki's auto-generated topic structure for a repository against the local documentation tree, producing a gap analysis.
|
Package wikidiff compares DeepWiki's auto-generated topic structure for a repository against the local documentation tree, producing a gap analysis. |
|
workspace
Package workspace manages the three-layer fork relationship: upstream (canonical repo) → fork (user's GitHub copy) → local (clone on disk).
|
Package workspace manages the three-layer fork relationship: upstream (canonical repo) → fork (user's GitHub copy) → local (clone on disk). |
|
worktree
Package worktree manages a pool of Git worktrees for concurrent file processing.
|
Package worktree manages a pool of Git worktrees for concurrent file processing. |
|
pkg
|
|
|
orchestrator
Package orchestrator provides generic multi-agent coordination primitives.
|
Package orchestrator provides generic multi-agent coordination primitives. |
|
session
Package session provides a vendor-agnostic JSONL session journal for recording LLM interactions.
|
Package session provides a vendor-agnostic JSONL session journal for recording LLM interactions. |
Click to show internal directories.
Click to hide internal directories.