takopi/mkdocs.yml

site_name: takopi
site_description: takopi — Telegram bridge for coding agents
site_url: https://banteg.github.io/takopi/

repo_url: https://github.com/banteg/takopi
repo_name: banteg/takopi
edit_uri: edit/master/docs/

docs_dir: docs
site_dir: _site

theme:
  name: material
  features:
    - navigation.sections
    - navigation.instant
    - navigation.tracking
    - content.code.copy
    - content.action.edit
    - search.suggest
    - search.highlight

markdown_extensions:
  - admonition
  - attr_list
  - tables
  - toc:
      permalink: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

plugins:
  - search
  - redirects:
      redirect_maps:
        architecture.md: explanation/architecture.md
        specification.md: reference/specification.md
        public-api.md: reference/plugin-api.md
        transports/telegram.md: reference/transports/telegram.md
        adding-a-runner.md: how-to/add-a-runner.md
        projects.md: reference/context-resolution.md
        runner/claude/claude-runner.md: reference/runners/claude/runner.md
        runner/claude/claude-stream-json-cheatsheet.md: reference/runners/claude/stream-json-cheatsheet.md
        runner/claude/claude-takopi-events.md: reference/runners/claude/takopi-events.md
        runner/codex/exec-json-cheatsheet.md: reference/runners/codex/exec-json-cheatsheet.md
        runner/codex/codex-takopi-events.md: reference/runners/codex/takopi-events.md
        runner/opencode/opencode-runner.md: reference/runners/opencode/runner.md
        runner/opencode/opencode-stream-json-cheatsheet.md: reference/runners/opencode/stream-json-cheatsheet.md
        runner/opencode/opencode-takopi-events.md: reference/runners/opencode/takopi-events.md
        runner/pi/pi-runner.md: reference/runners/pi/runner.md
        runner/pi/pi-stream-json-cheatsheet.md: reference/runners/pi/stream-json-cheatsheet.md
        runner/pi/pi-takopi-events.md: reference/runners/pi/takopi-events.md
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            show_source: false
  - llmstxt:
      markdown_description: |
        Takopi is a Telegram bridge for coding agents.
        For LLM ingestion, prefer the linked `.md` pages (Diátaxis: Tutorials / How-to / Reference / Explanation).
      full_output: llms-full.txt
      sections:
        Start here:
          - index.md: Overview + doc map
          - tutorials/install-and-onboard.md: Install Takopi + onboarding
          - tutorials/first-run.md: First run
          - how-to/projects.md: Projects (routing)
          - how-to/worktrees.md: Worktrees (@branch)
          - how-to/topics.md: Telegram topics
          - how-to/file-transfer.md: File transfer
        Reference:
          - reference/commands-and-directives.md: Commands, directives, and CLI flags
          - reference/config.md: Config schema and defaults
          - reference/specification.md: Normative behavior spec
          - reference/plugin-api.md: Stable plugin API surface
          - reference/context-resolution.md: Directive parsing + worktree rules
          - reference/transports/telegram.md: Telegram transport details
        Contributors & agents:
          - how-to/dev-setup.md: Dev setup + checks
          - explanation/module-map.md: Module responsibilities
          - reference/env-vars.md: Environment variables
          - reference/agents/invariants.md: Critical invariants
          - reference/agents/repo-map.md: Codebase entrypoints
        Optional:
          - reference/runners/index.md: Runner docs index
          - reference/runners/claude/stream-json-cheatsheet.md: Claude stream-json notes
          - reference/runners/codex/exec-json-cheatsheet.md: Codex exec --json notes

nav:
  - Home: index.md
  - Tutorials:
      - Overview: tutorials/index.md
      - Install & onboard: tutorials/install-and-onboard.md
      - First run: tutorials/first-run.md
  - How-to:
      - Overview: how-to/index.md
      - Switch engines: how-to/switch-engines.md
      - Projects: how-to/projects.md
      - Worktrees: how-to/worktrees.md
      - Route by chat: how-to/route-by-chat.md
      - Topics: how-to/topics.md
      - Voice notes: how-to/voice-notes.md
      - File transfer: how-to/file-transfer.md
      - Schedule tasks: how-to/schedule-tasks.md
      - Troubleshooting: how-to/troubleshooting.md
      - Write a plugin: how-to/write-a-plugin.md
      - Add a runner: how-to/add-a-runner.md
      - Dev setup: how-to/dev-setup.md
  - Reference:
      - Overview: reference/index.md
      - Commands & directives: reference/commands-and-directives.md
      - Configuration: reference/config.md
      - Environment variables: reference/env-vars.md
      - Specification: reference/specification.md
      - Plugin API: reference/plugin-api.md
      - Context resolution: reference/context-resolution.md
      - Telegram transport: reference/transports/telegram.md
      - Runners:
          - Overview: reference/runners/index.md
          - Claude:
              - Runner: reference/runners/claude/runner.md
              - Stream JSON cheatsheet: reference/runners/claude/stream-json-cheatsheet.md
              - Takopi events: reference/runners/claude/takopi-events.md
          - Codex:
              - Exec JSON cheatsheet: reference/runners/codex/exec-json-cheatsheet.md
              - Takopi events: reference/runners/codex/takopi-events.md
          - OpenCode:
              - Runner: reference/runners/opencode/runner.md
              - Stream JSON cheatsheet: reference/runners/opencode/stream-json-cheatsheet.md
              - Takopi events: reference/runners/opencode/takopi-events.md
          - Pi:
              - Runner: reference/runners/pi/runner.md
              - Stream JSON cheatsheet: reference/runners/pi/stream-json-cheatsheet.md
              - Takopi events: reference/runners/pi/takopi-events.md
      - For agents:
          - Agent entrypoint: reference/agents/index.md
          - Repo map: reference/agents/repo-map.md
          - Invariants: reference/agents/invariants.md
  - Explanation:
      - Overview: explanation/index.md
      - Architecture: explanation/architecture.md
      - Routing & sessions: explanation/routing-and-sessions.md
      - Plugin system: explanation/plugin-system.md
      - Module map: explanation/module-map.md