goga-tool-mkdocs 1.0.0__tar.gz

goga_tool_mkdocs-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: Release docs
+on:
+  push:
+    branches:
+      - '[0-9]+.[0-9]+.x'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs]"
+
+      - name: Build and Deploy
+        run: mkdocs gh-deploy --force

goga_tool_mkdocs-1.0.0/.github/workflows/new_version.yml

@@ -0,0 +1,21 @@
+name: Open New Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      type:
+        description: "New version type"
+        required: true
+        type: choice
+        options: [minor, major]
+
+permissions:
+  contents: write
+
+jobs:
+  create-branch:
+    uses: qarium/ci/.github/workflows/library-new-version.yml@0.0.x
+    with:
+      type: ${{ inputs.type }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}

goga_tool_mkdocs-1.0.0/.github/workflows/notify.yml

@@ -0,0 +1,17 @@
+name: Notify Release
+
+on:
+  workflow_run:
+    workflows: ["Publish Release"]
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  notify:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    uses: qarium/ci/.github/workflows/library-notify.yml@0.0.x
+    secrets:
+      TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
+      TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}

goga_tool_mkdocs-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: qarium/ci/.github/workflows/library-publish.yml@0.0.x
+    with:
+      src-package: goga_tool_mkdocs
+    secrets:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+      ZAI_TOKEN: ${{ secrets.ZAI_TOKEN }}

goga_tool_mkdocs-1.0.0/.gitignore

@@ -0,0 +1,225 @@
+# goga: ralphex config managed by goga
+.goga/prompts/*.txt
+.goga/agents/*.txt
+.goga/config
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+/MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# IDE
+.idea/
+
+# AI
+.claude/
+.ralphex/
+docs/tasks/
+docs/plans/
+docs/design/
+docs/arch/
+docs/superpowers/

goga_tool_mkdocs-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Mikhail Trifonov
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

goga_tool_mkdocs-1.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: goga-tool-mkdocs
+Version: 1.0.0
+Summary: Goga tool. MkDocs documentation skills.
+License: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Dynamic: license-file
+
+# goga-tool-mkdocs
+
+MkDocs documentation maintenance tool for the Goga framework.
+
+## Documentation
+
+[https://qarium.github.io/goga-tool-mkdocs](https://qarium.github.io/goga-tool-mkdocs)

goga_tool_mkdocs-1.0.0/README.md

@@ -0,0 +1,7 @@
+# goga-tool-mkdocs
+
+MkDocs documentation maintenance tool for the Goga framework.
+
+## Documentation
+
+[https://qarium.github.io/goga-tool-mkdocs](https://qarium.github.io/goga-tool-mkdocs)

goga_tool_mkdocs-1.0.0/docs/getting-started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install goga-tool-mkdocs
+```
+
+## Connect to agent
+
+Install skills into a Goga agent:
+
+```bash
+goga connect <agent>
+```
+
+## Requirements
+
+- Python 3.10+
+- Goga CLI
+
+## Usage
+
+Run the tool from a Goga project root:
+
+```bash
+/goga:tool mkdocs
+```
+
+The tool detects the execution mode automatically:
+
+- If no prior documentation state exists (no `mkdocs.yml`, no `docs/`), it runs in **bootstrap** mode
+- If documentation already exists, it runs in **incremental** mode and patches only affected areas
+
+## Project setup
+
+For the tool to produce documentation, your project should contain at least one of:
+
+- `CODEMANIFEST` files in cell directories
+- `.usages/` directories with practice files
+- `.tests/` directories with test specifications
+
+## Output
+
+The tool generates:
+
+- `docs/` directory with markdown pages
+- `mkdocs.yml` with navigation
+- `.goga/tools/mkdocs/traceability.yml` linking docs to source cells

goga_tool_mkdocs-1.0.0/docs/index.md

@@ -0,0 +1,36 @@
+# goga-tool-mkdocs
+
+MkDocs documentation maintenance tool for the Goga framework.
+
+## What it does
+
+`goga-tool-mkdocs` orchestrates creation, synchronization, patching, validation, and maintenance of MkDocs documentation using authoritative project artifacts.
+
+It is invoked via the Goga aggent command:
+
+```bash
+/goga:tool mkdocs
+```
+
+## How it works
+
+The tool runs a deterministic pipeline of subskills that discover project artifacts, analyze changes, build documentation structure, write content, synchronize navigation, and validate results.
+
+Two execution modes are available:
+
+- **Bootstrap** — generates documentation from scratch when no prior state exists
+- **Incremental** — patches existing documentation based on detected changes
+
+## Authoritative sources
+
+Documentation is generated from:
+
+- `CODEMANIFEST` files
+- `.usages/**/*.md` files
+- `.tests/**/*.yml` / `.tests/**/*.yaml` files
+
+## Quick links
+
+- [Getting Started](getting-started.md)
+- [Pipeline](pipeline.md)
+- [Skills](skills/mkdocs.md)

goga_tool_mkdocs-1.0.0/docs/overrides/main.html

@@ -0,0 +1,68 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+  {{ super() }}
+  <style>
+    /* Dark navbar — override palette in both themes */
+    [data-md-color-scheme=default][data-md-color-primary=custom],
+    [data-md-color-scheme=slate][data-md-color-primary=custom] {
+      --md-primary-fg-color: #0a0a13;
+      --md-primary-fg-color--light: #0a0a13cc;
+      --md-primary-bg-color: #ffffff;
+    }
+
+    .md-header__button.md-logo img,
+    .md-header__button.md-logo svg {
+      width: 32px;
+      height: 32px;
+      border-radius: 50%;
+    }
+
+    /* Search form — visible on dark header */
+    .md-search__overlay {
+      background-color: transparent !important;
+    }
+    [data-md-toggle=search]:checked~.md-header .md-search__overlay {
+      background-color: #0000008a !important;
+    }
+    .md-search__inner {
+      background-color: transparent !important;
+    }
+    .md-search__form {
+      background-color: #3a3a3a !important;
+      border-radius: 0.5rem;
+    }
+    .md-search__form:hover {
+      background-color: #4a4a4a !important;
+    }
+    .md-search__input {
+      color: #e0e0e0 !important;
+    }
+    .md-search__input::placeholder {
+      color: #999999 !important;
+    }
+    .md-search__icon {
+      color: #999999 !important;
+    }
+    .md-search__form:hover .md-search__icon,
+    .md-search__input:focus-visible ~ .md-search__icon {
+      color: #e0e0e0 !important;
+    }
+
+    /* Links in dark theme — readable on dark background */
+    [data-md-color-scheme=slate] .md-nav__link,
+    [data-md-color-scheme=slate] .md-toc__link,
+    [data-md-color-scheme=slate] article a {
+      color: #cbd5e0 !important;
+    }
+    [data-md-color-scheme=slate] .md-nav__link--passed,
+    [data-md-color-scheme=slate] .md-toc__link--passed {
+      color: #718096 !important;
+    }
+    [data-md-color-scheme=slate] .md-nav__link:hover,
+    [data-md-color-scheme=slate] .md-toc__link:hover,
+    [data-md-color-scheme=slate] article a:hover {
+      color: var(--md-accent-fg-color) !important;
+    }
+  </style>
+{% endblock %}

goga_tool_mkdocs-1.0.0/docs/pipeline.md

@@ -0,0 +1,67 @@
+# Pipeline
+
+The mkdocs tool executes a deterministic pipeline of subskills. The pipeline order differs between execution modes.
+
+## Traceability
+
+The tool maintains `.goga/tools/mkdocs/traceability.yml` — a mapping from documentation pages to source cell paths:
+
+```yaml
+docs/auth.md:
+  - auth/data
+  - auth/oauth
+```
+
+Rules:
+
+- Entries reference cell directory paths (e.g. `auth/data`), not files
+- Each cell path must exist as a directory with a `CODEMANIFEST` file
+- A page is linked to a cell if it uses information from that cell's `CODEMANIFEST` or `.usages/` files
+
+## Bootstrap mode
+
+Used when no prior documentation state exists.
+
+```
+1. Discovery       — scan project for authoritative sources
+2. Structure       — build documentation hierarchy
+3. Writer          — create documentation content
+4. Nav Sync        — generate mkdocs.yml navigation
+5. Validator       — validate consistency and integrity
+```
+
+## Incremental mode
+
+Used when documentation already exists. Adds impact analysis to detect what changed.
+
+```
+1. Discovery       — scan project for authoritative sources
+2. Impact Analysis — detect affected and stale documentation pages
+3. Structure       — update documentation hierarchy
+4. Writer          — patch stale sections, create missing ones
+5. Nav Sync        — update mkdocs.yml navigation
+6. Validator       — validate consistency and integrity
+```
+
+## Reconciliation loop
+
+If the validator returns `requires_reconciliation: true`, the pipeline re-runs a subset:
+
+```
+1. Impact Analysis
+2. Writer
+3. Nav Sync
+4. Validator
+```
+
+Maximum reconciliation loops: **2**.
+
+## Completion criteria
+
+The pipeline is complete when:
+
+- Documentation is synchronized with authoritative artifacts
+- Navigation is valid
+- Required sections exist
+- Stale docs are resolved
+- No blocking questions remain

goga_tool_mkdocs-1.0.0/docs/skills/discovery.md

@@ -0,0 +1,21 @@
+# discovery
+
+Discover authoritative documentation artifacts and public documentation surface.
+
+## Role
+
+Scans the repository to detect all sources that documentation should be generated from.
+
+## Workflow
+
+1. Scan repository
+2. Detect authoritative domains
+3. Detect `CODEMANIFEST` files
+4. Detect `.usages/` directories
+5. Detect `.tests/` directories
+6. Detect existing documentation
+7. Detect `mkdocs.yml`
+
+## Output
+
+Returns structured discovery results listing all found artifacts, existing documentation state, and any warnings about missing sources.

goga_tool_mkdocs-1.0.0/docs/skills/impact-analysis.md

@@ -0,0 +1,23 @@
+# impact-analysis
+
+Determine affected documentation areas and stale pages.
+
+## Role
+
+Analyzes changes (git diff) against the traceability mapping to identify which documentation pages need updating.
+
+## Workflow
+
+1. Analyze git diff
+2. Load traceability mapping
+3. Detect affected documentation pages
+4. Detect stale sections
+5. Detect required patches
+
+## When it runs
+
+Only in **incremental** mode and during reconciliation loops. Not part of the bootstrap pipeline.
+
+## Output
+
+Returns a deterministic patch plan listing affected pages, stale sections, and required patches.

goga_tool_mkdocs-1.0.0/docs/skills/mkdocs.md

@@ -0,0 +1,50 @@
+# mkdocs
+
+Master orchestration skill for MkDocs documentation maintenance.
+
+## Role
+
+Coordinates all subskills in deterministic order to create, synchronize, patch, validate, and maintain MkDocs documentation.
+
+## Invocation
+
+```text
+/goga:tool mkdocs
+```
+
+Invoked via the Goga tool agent command dispatcher. Not invoked directly by other skills.
+
+## Execution modes
+
+| Mode | When |
+|------|------|
+| Bootstrap | No prior documentation state exists |
+| Incremental | Documentation already exists, needs patching |
+
+## Subskills
+
+| Subskill | Purpose |
+|----------|---------|
+| [Discovery](discovery.md) | Discover authoritative artifacts |
+| [Impact Analysis](impact-analysis.md) | Detect affected and stale pages |
+| [Structure](structure.md) | Build documentation hierarchy |
+| [Writer](writer.md) | Create and patch content |
+| [Nav Sync](nav-sync.md) | Synchronize mkdocs.yml navigation |
+| [Validator](validator.md) | Validate consistency and integrity |
+| [Questions](questions.md) | Escalate blocking uncertainties |
+
+## Authoritative sources
+
+Documentation is generated from:
+
+- `CODEMANIFEST` — cell contract definitions
+- `.usages/**/*.md` — usage practice files
+- `.tests/**/*.yml` / `.tests/**/*.yaml` — test specifications
+
+## Traceability
+
+Maintains `.goga/tools/mkdocs/traceability.yml` mapping documentation pages to source cell paths.
+
+## Reconciliation
+
+If validation fails, the pipeline re-runs impact analysis through validator (max 2 loops).