Restructure docs and publish an OpenBot Mintlify site

[danielblignaut]

Outcome

Make docs/ a concise, navigable source of truth for users and contributors, and publish it as the official OpenBot documentation site with Mintlify.

This issue covers documentation information architecture, Mintlify configuration, migration of existing guides, validation, previews, and production publishing. It does not redesign the public marketing landing page; that is a companion issue.

Current state

• docs/ contains useful guides for agents, configuration, forks, providers, and sandboxes, plus durable ADRs.
• There is no site configuration, navigation model, preview workflow, hosted-docs validation, or canonical documentation URL.
• The root README currently has to serve installation, product overview, architecture, and contributor audiences at once.
• ADRs and end-user documentation share a directory but have different readers and maintenance rules.

Proposed information architecture

Use docs/ as the Mintlify project root rather than creating another documentation package:

docs/
  docs.json
  .mintignore
  index.mdx
  assets/
  get-started/
    overview.mdx
    install-desktop.mdx
    install-cli.mdx
    first-agent.mdx
    local-and-hosted.mdx
  guides/
    agents.mdx
    configuration.mdx
    providers.mdx
    computer-and-workspace.mdx
    secrets.mdx
    deployment.mdx
  reference/
    cli.mdx
    configuration.mdx
    directory-layout.mdx
    security-and-identity.mdx
    troubleshooting.mdx
  contributing/
    development.mdx
    testing.mdx
    releases.mdx
  adrs/
    ...existing records...

Keep the top-level navigation restrained:

1. Get started — choose desktop or CLI, install, and run the first agent.
2. Guides — accomplish common user and operator workflows.
3. Reference — exact commands, paths, configuration, security boundaries, and troubleshooting.
4. Contributing — repository setup, testing, architecture links, and releases.

Content ownership

• Public behavior is documented once under docs/; the root README becomes a short product/repository entry point that links into it.
• Package READMEs continue to own package-local implementation details. Public pages summarize and link rather than duplicating those details.
• docs/adrs/ remains the canonical, chronological record for durable decisions.
• Initially exclude ADR files from Mintlify navigation/search with .mintignore; expose an Architecture decisions link to the GitHub directory from the contributor section. This avoids turning implementation history into user guidance or rewriting ADRs solely for the site generator.
• Move the existing agent, configuration, fork, provider, and sandbox guides into the new structure while preserving GitHub links and adding redirects for any previously published paths.
• Examples must use inert identifiers and placeholders. Never publish real keys, setup codes, webhook secrets, browser data, or deployment state.

Mintlify architecture

• Commit docs/docs.json and all navigation, branding, redirects, and site settings. Do not rely on dashboard-only configuration.
• Configure the Mintlify project as a monorepo deployment whose documentation path is docs.
• Connect the repository through the Mintlify GitHub integration so merges to the protected production branch publish the site and pull requests get previews.
• Use a dedicated docs domain or subdomain. Keep the domain value configurable until the canonical OpenBot domains are selected.
• Reuse repository-owned wordmarks, icons, colors, and code examples; do not introduce a second brand source of truth.
• Enable Mintlify's agent-readable documentation outputs and verify their live URLs as part of release smoke tests.
• Keep analytics disabled until an owner and privacy policy are selected; documentation must work without cookies, authentication, or control-plane access.

Validation and CI

Add a focused docs job to the repository CI/release work tracked in #31. Pin the supported Node runtime (currently Node 24 for this repository) and run:

mint validate
mint broken-links
mint a11y

Also validate:

• internal and external links;
• navigation entries and redirect targets;
• desktop/CLI installation commands against the actual packages and release artifacts;
• mobile navigation and keyboard accessibility;
• code blocks and shell commands render as continuous, syntax-highlighted blocks;
• production domain, canonical metadata, sitemap, and agent-readable documentation endpoints after deployment.

Delivery slices

1. Add docs.json, branding assets, navigation, and a local preview command.
2. Migrate existing Markdown into the proposed information architecture without losing technical content.
3. Tighten the root README and add cross-links from package documentation.
4. Add validation to CI and document the preview workflow.
5. Connect Mintlify, configure the canonical domain, publish from the protected branch, and smoke-test the live site.

Acceptance criteria

• docs/ is the only source directory for the hosted documentation site.
• A new user can choose desktop or CLI and reach a working first-agent flow without reading repository internals.
• Existing agent, configuration, fork, provider, and sandbox guidance is migrated or intentionally retired with a redirect/link.
• ADRs remain unchanged as durable records and are not mixed into user navigation.
• Mintlify configuration, navigation, branding, and redirects are source-controlled.
• Pull requests receive documentation previews and the production branch publishes automatically.
• Docs validation, broken-link checking, and accessibility checking run in CI.
• The live site exposes correct canonical metadata and agent-readable documentation endpoints.
• No secret, private endpoint, browser data, or generated deployment state is published.

Open decisions

• Canonical documentation domain and whether it is a subdomain or a path under the marketing domain.
• Whether selected ADRs should later get curated public summaries under a small Architecture section.
• Whether CLI/configuration reference should remain hand-authored with source checks or be generated from schemas/help output.

Related work

• Establish GitHub CI/CD and a secure release process #31 — GitHub CI/CD and release process
• Sign, notarize, and productize the macOS Electron app #32 — desktop CLI packaging and release artifacts
• Launch a public OpenBot landing page #36 — public OpenBot landing page