Maidan documentation
Documentation for Maidan is GitHub-native Markdown: standard links, headings, and Mermaid fenced blocks. It renders correctly on GitHub, in mdBook, and in editors.
Published site: https://david-engelmann.github.io/maidan/ (mdBook). A maidan.world product domain (landing + /docs + /blog) is planned for the public preview but is not registered/live yet — the cutover plan is in Promotion.md; use the GitHub Pages URL today.
External integrators: Integration.md — do not start with cluster plans.
Repo contributors: CLAUDE.md — operating manual, then this index.
Post-272 forward work: the canonical backlog is Open Work.md / Roadmap.md. The strategy pack (Handoff.md → Pre-Public Hardening, Path to Impressive, Expansion Bets, Launch, Protocols, Providers) is the rationale and detailed scoping behind those items — read it for the "why," not as a separate backlog.
Obsidian (optional, local only): open
docs/as a vault for graph view. Some historical notes still containwikilinks; prefer the published site or Integration.md for links that must work on GitHub.
Integrate with Maidan
| Doc | Audience |
|---|---|
| Integration.md | Agents, bots, client apps — start here |
| Capability Map.md | Capability strings + contracts/*.json |
| Production.md | Probes, env vars, bootstrap, metrics |
| Embeddings.md | Embedding providers, per-model tables, switching models (reindex) |
| Providers.md | Plug-in matrix: DB hosts, S3, embeddings, OIDC, SMTP |
| Protocols.md | Integration wires: MCP, A2A, REST, WS, webhooks — what we speak vs 2026 stack |
| Deploy.md | Docker Compose, Kubernetes, Helm |
| Pi.md | Raspberry Pi / ARM64 Linux |
| Threat-Model.md | Security assets and controls |
| Glossary.md | Domain vocabulary |
Generated on each merge: MCP tool reference (from book/src/mcp-reference.md).
Live API: GET /openapi.json on your server.
Design and operations (maintainers)
| Doc | Purpose |
|---|---|
| Architecture.md | Components and data flow |
| Capabilities.md | What shipped in each release (append-only) |
| Decisions.md | Architectural decisions (ADRs) |
| Conventions.md | Branch, commit, PR conventions |
| Operations.md | PR flow, CI, releases |
| Dependencies.md | Dependency currency + duplicate-version policy (deny.toml) |
| Gates/maidan-scale-1.0.md | Scale product gate (v120.0.0): criteria → evidence |
| Handoff.md | Strategy index for post-272 forward work (feeds Open Work.md; IDs, try-out matrix, rationale) |
| Launch.md | Production-ready extras, public-preview cut, when you may announce |
| Promotion.md | Get the word out: maidan.world, docs hub, Show HN, Reddit, LinkedIn, Medium |
| Pre-Public Hardening.md | Cleanup/refactor/tests/docs before a public launch |
| Path to Impressive.md | Strategy: UI assurance, adoption gaps, usefulness bets |
| Expansion Bets.md | Researched feature bets after 270-272 (Slack teammate, MCP pack, SDKs, mail queue) |
| Open Work.md | Short backlog + risks |
| Remaining Work.md | Exhaustive backlog matrix |
| Roadmap.md | Cluster ladder history |
| Post-1.0.md | Tracks after v1.0.0 |
Historical planning (not required for integration)
Cluster kickoff docs and retros document how the repo was built, not the runtime contract.
| Path | Contents |
|---|---|
| Clusters/ | Per-cluster PR ladders (may use Obsidian wikilinks) |
| Retros/ | Closing retrospectives |
| Tracks/ | Cross-cutting tracks T–X |
| Clusters/Product Ladder 77+.md | Operator ladder 77–101 (closed on main) |
Suggested read order
Integrating with a running server
- Integration.md
- Protocols.md if choosing MCP vs A2A vs REST vs webhooks
- Capability Map.md +
contracts/ - Production.md / Deploy.md / Providers.md as needed
Contributing to the repository
Layout
docs/
├── README.md this index
├── Integration.md canonical external integrator guide
├── Handoff.md post-D pack pickup (agents start here)
├── Launch.md public cut + announce
├── Providers.md host matrix
├── Protocols.md wire matrix
├── Architecture.md
├── Roadmap.md
├── Capabilities.md
├── Capability Map.md
├── Conventions.md
├── Operations.md
├── Decisions.md
├── Production.md
├── Deploy.md
├── Clusters/ historical planning
└── Retros/ historical retros
Conventions
- Prefer relative Markdown links (
[Title](File.md)) in new and integrator-facing docs. - Mermaid in fenced
```mermaidblocks (GitHub + mdBook). - Filenames may contain spaces; URL-encode in links (
%20) when required. - Older vault notes may use
wikilinksfor Obsidian only — do not add new wikilinks to integrator-facing pages.