feat(docs): scaffold Mintlify documentation site#55
Merged
Conversation
First slice of the public docs site — 13 MDX pages organised into Get-Started, Concepts, and CLI Reference sections. Brand v2 system applied (coral primary, paper/canvas backgrounds, Geist font, simplified C mark in logo + favicon). Pages shipped: - introduction.mdx — landing - quickstart.mdx — 5-minute first run - installation.mdx — prerequisites + setup.sh walkthrough - concepts/overview.mdx — five primitives + design principles - concepts/the-plan.mdx — 8 required sections, schema, edit-mid-project - concepts/the-oracle.mdx — tiered metric, statistical significance, examples - concepts/agents.mdx — 20 agents, two teams, tier routing, customisation - concepts/phases-and-gates.mdx — 6 phases, 3 gate types, autonomous loop - concepts/memory-and-continuity.mdx — STATE/DECISION_LOG/PRIORS, .zo/, semantic search - cli/overview.mdx — pipeline, modes, all commands at a glance - cli/init.mdx — full reference with layout modes + dry-run + reset - cli/draft.mdx — Plan Architect + scouts, custom agents, adaptations - cli/build.mdx — flagship command, smart mode detection, gate modes Brand assets: - docs/logo/light.svg (ink stroke + coral dot for paper bg) - docs/logo/dark.svg (cream stroke + coral dot for canvas bg) - docs/favicon.svg (coral simplified C, mid-tone for browser tabs) mint.json brand config: primary #D87A57, light bg #F4EFE6 (paper), dark bg #12110F (canvas), Geist headings + body, footer GitHub link, search prompt, suggest-edit + raise-issue feedback. Existing docs/*.md files (COMMANDS, SAMPLE_PROJECT, TROUBLESHOOTING, DELIVERY_STRUCTURE) stay in place during transition — the README still links to them. docs/README.md documents local dev (mintlify dev), the file structure, brand tokens, deploy steps, and the migration table from existing .md sources to MDX destinations. Framework decision rationale (vs Astro Starlight) recorded in DECISION_LOG: Mintlify wins on user adoption — pattern recognition (Anthropic/Vercel/Linear/Cursor all use Mintlify), built-in AI search, positioning signal, battle-tested mobile + edge-cases, lower maintenance burden = fresher docs over time. Brand fidelity matters most on the marketing site; docs prioritise speed-to-answer. Deploy: connect Mintlify to the GitHub repo (one-click on mintlify.com, free OSS plan), point at docs/, attach docs.zero-operators.dev custom domain. Auto-deploys on push to main thereafter. This commit updates PR #54 (v1 completion) — docs scaffold is part of the v1 story. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying zero-operators with
|
| Latest commit: |
7fa38b8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://29155d7c.zero-operators.pages.dev |
| Branch Preview URL: | https://claude-focused-hugle-44c2f3.zero-operators.pages.dev |
SamPlvs
added a commit
that referenced
this pull request
Apr 30, 2026
feat(docs): scaffold Mintlify documentation site
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First slice of the public Zero Operators documentation site, built with Mintlify under
docs/. 13 MDX pages organised into Get-Started, Concepts, and CLI Reference sections, branded with the v2 design system.Deploys to
docs.zero-operators.dev(free Mintlify OSS plan) once Mintlify is connected to this repo.What ships
Configuration + assets
docs/mint.json— nav, colours, logo, search, feedback widgetsdocs/logo/light.svg+docs/logo/dark.svg— simplified C mark + Geist wordmarkdocs/favicon.svg— coral C mark, mid-tone (visible on light + dark browser tabs)13 MDX pages
Get started
introduction.mdx— landing, the four primitives, the six-phase flow, the four-source thesisquickstart.mdx— five minutes fromgit cloneto a deployed modelinstallation.mdx— prereqs (Claude CLI, Python 3.11+, uv, tmux),setup.shwalkthrough, manual install tabsConcepts
concepts/overview.mdx— five primitives + design principlesconcepts/the-plan.mdx— eight required sections, schema, edit-mid-projectconcepts/the-oracle.mdx— tiered metric, statistical significance, examples (MNIST + CIFAR-10 + time-series)concepts/agents.mdx— 20 agents, two teams, tier routing, per-project customisationconcepts/phases-and-gates.mdx— 6 phases, 3 workflow modes, gate types + decisions, autonomous experiment loop, phase snapshotsconcepts/memory-and-continuity.mdx— STATE/DECISION_LOG/PRIORS,.zo/portable layout, cross-machine, semantic search, self-evolutionCLI reference
cli/overview.mdx— canonical pipeline, modes, every command at a glancecli/init.mdx— full reference with layout modes + dry-run + resetcli/draft.mdx— Plan Architect + scouts, custom agents, adaptationscli/build.mdx— flagship command, smart mode detection, gate modes, monitoringBrand v2 applied
#D87A57(coral)#F4EFE6(paper) / dark bg#12110F(canvas)Why Mintlify (vs Astro Starlight)
Decision recorded in DECISION_LOG.md. Short version: user adoption wins over brand fidelity.
Brand fidelity matters most on the marketing site (
website/) — that's where prospects evaluate the product. In docs, users want speed-to-answer, not typography continuity.Coexistence with existing docs
Existing
docs/COMMANDS.md,docs/SAMPLE_PROJECT.md,docs/TROUBLESHOOTING.md,docs/DELIVERY_STRUCTURE.mdstay in place during transition — the root README still links to them.docs/README.mdincludes a migration table tracking which existing files map to which planned MDX destinations. They'll be retired once the docs site is live and the migration is complete.Deploy steps (manual, one-time)
SamPlvs/zero-operatorsGitHub repo.docs/directory.docs.zero-operators.devcustom domain in Mintlify dashboard.After setup, every push to
mainthat touchesdocs/re-deploys.Local development
Validation
mint.jsonis valid JSONvalidate-docs.sh10/10 (1 unrelated pre-existing test-count badge warning)README.mdupdated withdocs.zero-operators.devbadgeFollow-up (planned, not in this PR)
cli/{preflight, continue, status, experiments, gates, migrate, watch-training}.mdxtutorials/{mnist, cifar10}.mdx(use the v1 demo deliverables we shipped in feat: complete v1 — platform-aware scaffold + MNIST/CIFAR-10 demos #54)reference/{plan-schema, agents, slash-commands, workflow-modes}.mdxarchitecture/{repo-separation, orchestration, self-evolution}.mdxresources/{troubleshooting, changelog, priors, contributing}.mdxdocs/*.mdfiles once migration is completeTest plan
mint.jsonvalidates as JSONvalidate-docs.shpasses (unchanged from main)docs.zero-operators.devresolves (manual, post-deploy)🤖 Generated with Claude Code