mkdocs.yml

site_name: Mewbo
site_description: Documentation for Mewbo, an AI assistant modeled as a conversation state machine with a hierarchical agent hypervisor. Use it from the terminal, the web console, Android, the REST API, and Home Assistant.
repo_url: https://github.com/bearlike/Assistant
repo_name: bearlike/Assistant
site_url: https://docs.mewbo.com/

theme:
  name: shadcn
  favicon: logos/favicon.ico
  icon: logos/logo-transparent.svg

  # Header tab rail (theme >= 1.3.0): fused below the top utility row, one
  # sticky surface. Since theme 1.6.0 a tab may claim a top-level nav Section
  # (`section:`): pages inside a claimed section get a sidebar scoped to that
  # section, and every other page gets the full nav minus all claimed sections.
  # `match:` lists extra URL prefixes that also activate the tab; the API tab
  # uses it so the full-page Scalar reference (docs/rest-api.md, app.html
  # template, URL rest-api/) highlights the API Reference tab.
  header_tabs:
    - label: Documentation
      icon: lucide:book-open
      url: .
    - label: Terminal
      icon: lucide:terminal
      url: terminal/
      section: Terminal
    - label: Web
      icon: lucide:layout-dashboard
      url: web/
      section: Web
    - label: Android
      icon: lucide:smartphone
      url: android/
      section: Android
    - label: API Reference
      icon: lucide:braces
      url: api/
      section: API
      match:
        - rest-api

  # Mewbo brand-fork (mkdocs-shadcn-mewbo) configuration ────────────────
  ai:
    deepwiki_repo: bearlike/Assistant
    question_prefix: |
      Answer for a working engineer. Be concrete and cite the source.
    # Setup questions are answered better by Get Started than by a model, and
    # a reader who is still installing is not the one who opens Ask AI. These
    # are the questions someone already running Mewbo asks: what it does under
    # load, what it costs, what stops it, and how to wire it into work they
    # already have.
    examples:
      - "Can a sub-agent spawn its own sub-agents?"
      - "What stops a shell command reading another project?"
      - "How do I cap what one session can spend?"
      - "Can a trigger open a pull request?"
      - "How do I get JSON I can pipe into something else?"
      - "What happens when a model call fails halfway?"
  # Code-reference badges (theme >= 1.4.0): authors write `repo:`/`endpoint:`
  # link schemes and the theme rewrites them into DeepWiki-style badges. File
  # badges auto-derive from repo_url (GitHub blob at the build SHA); endpoint
  # badges deep-link into the Scalar reference page below. The tags map MUST
  # stay in sync with the tag names the spec actually carries: RETAG_RULES in
  # scripts/ci/generate_openapi_spec.py, PLUS the tags its defensive fallback
  # derives from a path's first segment for route families RETAG_RULES does not
  # name (`Apps` is one). A prefix missing here is silent: the badge still
  # renders, it just loses its `#tag/...` anchor and lands on the reference top.
  # 38 pages carry a table of more than ten rows. Loads Tablesort (MIT) and
  # makes prose tables click-to-sort; a pygments line-number table is excluded
  # structurally. Opt a table out with `data-no-sort`.
  sortable_tables: true
  code_refs:
    endpoint:
      reference_page: rest-api/
      tags:
        /api/sessions: Sessions
        /api/query: Sessions
        /api/commands: Sessions
        /api/share: Sessions
        /api/projects: Projects & Worktrees
        /api/v_projects: Projects & Worktrees
        /api/keys: API Keys
        /api/models: Models
        /api/tools: Tools & Skills
        /api/skills: Tools & Skills
        /api/plugins: Plugins
        /api/apps: Apps
        /api/notifications: Notifications
        /api/config: Configuration
        /api/agentic_search/workspaces: Workspaces & Runs
        /api/agentic_search/runs: Workspaces & Runs
        /api/agentic_search/sources: Source Graph
        /api/agentic_search/scg: Source Graph
        /v1/structured: Structured Outputs
        /v1/draft: Draft Streaming
        /v1/wiki: Wiki Ingestion
        /api/triggers: Triggers
        /api/automation: Automation
  versions_root: Assistant
  show_version_switcher: true
  show_build_info: true
  # Hero product-tour carousel: the theme emits Swiper (CDN) + its SRI-hashed
  # init and styles `.ms-shots`; the landing page only writes the
  # `.swiper.ms-shots` markup. One local override exists for this box's
  # aspect ratio — see the `extra_css` entry below.
  carousel: true
  lightbox: true
  link_check: true
  # Footer "Connect" column: GitHub is auto-filled from repo_url; the email
  # button is appended right after it (the theme ships an email→lucide:mail alias).
  footer:
    social:
      email: mailto:hello@mewbo.com
    # Shortlist the footer's auto-derived Documentation column (theme >= 1.6.1).
    # Everything else stays reachable from the header tabs and the sidebar.
    docs:
      - Get Started
      - Terminal
      - Web
      - Android
      - API
  nav_icons:
    "Start here": lucide:compass
    Home: lucide:house
    "Get Started": lucide:rocket
    Troubleshooting: lucide:life-buoy

    Terminal: lucide:terminal
    "The Interface": lucide:panels-top-left
    "Agent Fleet": lucide:users
    "Remote Sync": lucide:cloud
    Configuration: lucide:sliders-horizontal

    Web: lucide:layout-dashboard
    Sessions: lucide:messages-square
    "Search and Wiki": lucide:telescope
    Panels: lucide:layout-panel-top

    Android: lucide:smartphone
    Install: lucide:download
    Voice: lucide:mic
    "Chat and Sessions": lucide:messages-square
    "Device Tools": lucide:smartphone-nfc

    API: lucide:webhook
    Automation: lucide:bot
    Triggers: lucide:alarm-clock
    "Device Tool Bridge": lucide:cable
    "Full Reference": lucide:globe

    "Client Integrations": lucide:cable
    "Mewbo as an MCP Server": lucide:plug-zap
    "Home Assistant": lucide:house-plug
    "Nextcloud Talk": lucide:message-circle
    Email: lucide:mail

    "Working with Mewbo": lucide:sparkles
    "Workspace & Execution": lucide:hammer
    "Built-in Tools": lucide:wrench
    "Branches & Worktrees": lucide:git-fork
    "Web IDE": lucide:code-xml
    Widgets: lucide:panel-left
    "Code Intelligence": lucide:zap
    "External MCP Tools": lucide:plug
    "Agentic Wiki": lucide:book-marked
    Overview: lucide:book-open
    "Indexing & Generation": lucide:database
    "Question Answering": lucide:message-circle-question
    "Knowledge Graph": lucide:waypoints
    "Agentic Search": lucide:search
    "Source Capability Graph": lucide:route
    "Agentic Apps": lucide:app-window
    "Building an App": lucide:hammer
    "Living with an App": lucide:heart-pulse
    "Structured Outputs": lucide:brackets
    "Composition & Delegation": lucide:users
    "Sub-agents": lucide:git-branch
    Skills: lucide:graduation-cap
    "Plugins & Marketplace": lucide:puzzle
    "Control & Safety": lucide:shield
    "Plan Mode": lucide:clipboard-list
    "Sandboxed Execution": lucide:shield-half
    "Permissions & Hooks": lucide:lock
    Policies: lucide:shield-check
    Monitors: lucide:eye
    "Token Usage": lucide:coins
    Compaction: lucide:archive

    Deploy: lucide:package
    "Docker Compose": lucide:container
    "Storage Backends": lucide:database
    "Production Setup": lucide:server

    Configure: lucide:sliders-horizontal
    "LLM Setup": lucide:brain
    "Project Setup": lucide:folder-cog
    "Authentication & Access": lucide:key-round
    "Identity Providers": lucide:fingerprint
    Authelia: lucide:shield-check
    Authentik: lucide:shield-check
    Google: lucide:shield-check
    Keycloak: lucide:shield-check
    "Microsoft Entra ID": lucide:shield-check
    AWS: lucide:shield-check
    "LDAP & Active Directory": lucide:server
    "Configuration Reference": lucide:file-json

    Develop: lucide:code
    "Architecture Overview": lucide:blocks
    "Session Runtime": lucide:cpu
    "Building a Client": lucide:hammer
    "Python Reference": lucide:book-open-text

hooks:
  - docs/hooks/schema_to_md.py
  - docs/hooks/redirects.py

markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
      linenums: false
      css_class: codehilite
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.inlinehilite
  # Renders ++ctrl+shift+a++ as real <kbd> elements, both Mac and Windows
  # modifiers. The theme has styled <kbd> for a long time; nothing emitted it,
  # so shortcuts were written as prose or inline code.
  - pymdownx.keys
  # `abbr` turns an `*[TERM]: expansion` definition into <abbr title="...">,
  # which the browser renders as a tooltip. This site enables extensions
  # individually rather than through `extra`, so abbr has to be named here —
  # without it the glossary below is appended to every page and silently does
  # nothing, which is exactly how it first shipped.
  - abbr
  # Appends the glossary to every page, so a definition written once gives
  # that acronym a tooltip everywhere it appears.
  - pymdownx.snippets:
      # base_path resolves from the mkdocs.yml directory, NOT from docs/, so
      # a bare `includes/...` silently resolves to a repo-root path that does
      # not exist — and snippets appends nothing rather than erroring.
      base_path:
        - docs
      auto_append:
        - includes/abbreviations.md
  - admonition
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
  # The `///` blocks API, enabled alongside the older `=== "…"` tabbed syntax
  # above. Both are kept because existing pages use `===`, and a blocks tab
  # takes a fenced code sample without the four-space indent `===` forces.
  # A page repeating itself once per platform or per provider collapses into
  # one tab set, which is the cheapest large word cut available on this site.
  - pymdownx.blocks.tab:
      alternate_style: true
  # A table caption says what a table is for in one line and numbers it. A page
  # that loses 40% of its prose usually loses that sentence first.
  - pymdownx.blocks.caption
  - pymdownx.blocks.details
  - footnotes
  - tables
  - attr_list
  - md_in_html
  # Every one of the extensions above is a SILENT dependency. An unenabled
  # block renders as literal text in the page and `strict: true` still passes,
  # so a snippet copied from a newer theme version fails by shipping, not by
  # erroring. Never circulate a syntax before checking it is named here.
  - toc:
      permalink: true

exclude_docs: |
  superpowers/
  includes/
  hooks/
  CLAUDE.md
  assets/img-src/

# MkDocs only reports anchors, orphaned pages and absolute links at INFO by
# default, so `--strict` alone lets a link to a heading that no longer exists
# ship silently. Raising them to `warn` is what makes `make docs-build` fail on
# one. Never lower these to silence a build — fix the link or the nav entry.
# Warnings fail the build. Set here rather than as a `--strict` CLI flag so it
# also covers the versioned-publish path, which builds mkdocs internally and
# accepts no strict flag of its own — that leg would otherwise stay unvalidated.
strict: true

validation:
  nav:
    omitted_files: warn
    not_found: warn
    absolute_links: warn
  links:
    not_found: warn
    anchors: warn
    absolute_links: warn
    unrecognized_links: warn

plugins:
  - search
  - callouts:
      aliases: false
  - mkdocstrings:
      handlers:
        python:
          paths:
            - .
            - apps
            - packages/mewbo_core/src
            - packages/mewbo_tools/src
            - packages/mewbo_graph/src
            - apps/mewbo_api/src
            - apps/mewbo_cli/src
          options:
            docstring_style: google
            show_source: true
            show_signature_annotations: true
            show_root_heading: true
            show_root_toc_entry: false

# The one local stylesheet this site ships. mkdocs-shadcn-mewbo's
# `.ms-shots img` carousel box is fixed at a 4:3 aspect ratio; every image a
extra:
  version:
    provider: mike

# Theme ships everything that used to live in extra_css/extra_javascript and
# overrides/ — including the hero product-tour carousel (theme.carousel above
# emits Swiper + its init and styles `.ms-shots`, at 16:9 since v1.10.1, which
# retired the one-rule bridge this site used to carry). If you ever need to
# override theme behavior,
# you can add `theme.custom_dir: overrides`, but the brand chrome / Ask AI /
# nav icons / version switcher / SEO / speculation prefetch / build-info badge
# are all already provided.

nav:
  - Start here:
      - Home: index.md
      - Get Started: getting-started.md
  - Terminal:
      - Get Started: terminal/index.md
      - The Interface: terminal/interface.md
      - Agent Fleet: terminal/agent-fleet.md
      - Remote Sync: terminal/remote-sync.md
      - Configuration: terminal/configuration.md
  - Web:
      - Get Started: web/index.md
      - Sessions: web/sessions.md
      - Search and Wiki: web/search-and-wiki.md
      - Web IDE: web/ide.md
      - Panels: web/panels.md
      - Widgets: web/widgets.md
  - Android:
      - Get Started: android/index.md
      - Install: android/install.md
      - Voice: android/voice.md
      - Chat and Sessions: android/chat.md
      - Device Tools: android/device-tools.md
  - API:
      - Get Started: api/index.md
      - Building a Client: api/building-a-client.md
      - Structured Outputs: api/structured-outputs.md
      - Automation: api/automation.md
      - Triggers: api/triggers.md
      - Device Tool Bridge: api/device-tools.md
      - Full Reference: rest-api.md
  # "Working with Mewbo" holds the three products and nothing else. The
  # capability groups below it are how Mewbo works rather than what it ships,
  # so they sit alongside as their own groups instead of nesting three deep.
  - Working with Mewbo:
      - Agentic Wiki:
          - Overview: features-wiki.md
          - Indexing & Generation: features-wiki-indexing.md
          - Question Answering: features-wiki-qa.md
          - Knowledge Graph: features-wiki-graph.md
      - Agentic Search:
          - Overview: features-search.md
          - Source Capability Graph: features-search-scg.md
      - Agentic Apps:
          - Overview: apps/index.md
          - Building an App: apps/building.md
          - Living with an App: apps/operating.md
  - Workspace & Execution:
      - Built-in Tools: features-builtin-tools.md
      # The two MCP pages are the two DIRECTIONS of the protocol and are named
      # for the direction, not for the protocol, because naming both "MCP"
      # made readers open the wrong one. clients-mcp is Mewbo being the server
      # other agents call in to; features-mcp is Mewbo calling out to servers
      # you configure, and it closes the group.
      - Mewbo as an MCP Server: clients-mcp.md
      - Code Intelligence: features-lsp.md
      - Branches & Worktrees: features-worktrees.md
      - External MCP Tools: features-mcp.md
  - Control & Safety:
      - Plan Mode: features-plan-mode.md
      - Sandboxed Execution: features-sandbox.md
      - Permissions & Hooks: features-permissions-hooks.md
      - Policies: features-policies.md
      - Monitors: features-monitors.md
  - Composition & Delegation:
      - Plugins & Marketplace: features-plugins.md
      - Sub-agents: features-agents.md
      - Skills: features-skills.md
      - Compaction: features-compaction.md
  - Client Integrations:
      - Email: clients-email.md
      - Nextcloud Talk: clients-nextcloud-talk.md
      - Home Assistant: clients-home-assistant.md
  - Deploy:
      - Docker Compose: deployment-docker.md
      - Storage Backends: deployment-storage.md
      - Production Setup: deployment-production.md
      - Troubleshooting: troubleshooting.md
  - Configure:
      - LLM Setup: llm-setup.md
      - Project Setup: project-configuration.md
      - Authentication & Access:
          - Overview: authentication.md
          - Identity Providers: authentication-providers.md
          - Authelia: integrations-authelia.md
          - Authentik: integrations-authentik.md
          - Google: integrations-google.md
          - Keycloak: integrations-keycloak.md
          - Microsoft Entra ID: integrations-entra-id.md
          - AWS: integrations-aws.md
          - LDAP & Active Directory: integrations-ldap.md
      - Configuration Reference: configuration.md
  - Develop:
      - Architecture Overview: core-orchestration.md
      - Session Runtime: session-runtime.md
      - Python Reference: reference.md
      - Token Usage: features-token-usage.md