Add MkDocs docs site and GitHub Pages deployment

Author: Shashikant86

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install docs dependencies
+        run: uv sync --extra docs
+
+      - name: Build docs
+        run: |
+          uv run --no-sync mkdocs build --clean
+          touch site/.nojekyll
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          publish_branch: gh-pages
+          force_orphan: true
+

.gitignore

@@ -25,3 +25,4 @@ build/
 dist/
 *.egg-info/
 .codexopt/
+site/

README.md

@@ -1,5 +1,7 @@
 # CodexOpt
 
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://superagenticai.github.io/CodexOpt/)
+
 CodexOpt: Optimize your Agents.MD and Skills for Codex with GEPA
 
 ## Demo Repo
@@ -9,6 +11,15 @@ Want to see CodexOpt on a small, intentionally messy repository with sample
 
 - Demo: https://github.com/SuperagenticAI/codexopt-demo
 
+## Documentation
+
+- Docs site: https://superagenticai.github.io/CodexOpt/
+- Docs source: [`docs/`](/Users/shashi/oss/CodexOpt/docs)
+
+View the published documentation:
+
+- https://superagenticai.github.io/CodexOpt/
+
 CodexOpt is a lightweight Python CLI to improve Codex instruction assets with a repeatable loop:
 
 1. Scan instruction files.

assets/codexopt_favicon.png

@@ -0,0 +1,57 @@
+# Benchmarking
+
+CodexOpt computes a `0.0` to `1.0` score per file and records detailed feedback.
+
+## What Gets Scored
+
+### `AGENTS.md`
+
+Signals include:
+
+- too short or too long
+- token heaviness
+- empty files
+- contradictory guidance
+- duplicate lines
+- missing workflow guidance
+- missing verification guidance
+- missing output-format guidance
+- weak repo or task alignment
+
+### `SKILL.md`
+
+Signals include:
+
+- missing frontmatter
+- missing `name` or `description`
+- overly long frontmatter fields
+- weak trigger clarity
+- weak workflow guidance
+- weak verification guidance
+- weak repo or task alignment
+
+## Evidence-aware Feedback
+
+If `task_files` or `issue_files` are configured, benchmark output includes:
+
+- task file count
+- issue file count
+- criterion-level sub-scores
+- natural-language feedback
+
+## Example
+
+```bash
+codexopt --config codexopt.yaml benchmark
+```
+
+Typical output:
+
+```text
+overall_score: 0.6150
+task_files: 1
+issue_files: 1
+- agents: /path/to/AGENTS.md
+  score=0.4700 issues=contradictions, duplicate_lines, missing_output_contract
+```
+

assets/codexopt_logo.png

@@ -0,0 +1,75 @@
+# Configuration
+
+CodexOpt reads `codexopt.yaml` by default.
+
+## Example Config
+
+```yaml
+version: 1
+targets:
+  agents_files:
+    - AGENTS.md
+    - "**/AGENTS.md"
+    - "**/AGENTS.override.md"
+  skills_globs:
+    - ".codex/skills/**/SKILL.md"
+    - "**/.codex/skills/**/SKILL.md"
+  exclude_globs:
+    - ".git/**"
+    - ".codexopt/**"
+    - ".venv/**"
+    - "node_modules/**"
+    - "reference/**"
+output:
+  root_dir: ".codexopt"
+evidence:
+  task_files: []
+  issue_files: []
+optimization:
+  engine: "heuristic"
+  min_apply_delta: 0.01
+  max_metric_calls: 60
+  reflection_model: null
+```
+
+## Sections
+
+### `targets`
+
+Controls where CodexOpt looks for instruction assets.
+
+- `agents_files`: glob patterns for `AGENTS.md`
+- `skills_globs`: glob patterns for `SKILL.md`
+- `exclude_globs`: paths to ignore during discovery
+
+### `output`
+
+Controls artifact location.
+
+- `root_dir`: where runs, state, and backups are written
+
+### `evidence`
+
+Optional files that improve benchmarking and optimization quality.
+
+- `task_files`: markdown or JSON task lists
+- `issue_files`: markdown or JSON issue / review exports
+
+These do not yet execute full task simulations. They influence scoring and feedback.
+
+### `optimization`
+
+- `engine`: `heuristic` or `gepa`
+- `min_apply_delta`: minimum score gain required to keep a candidate
+- `max_metric_calls`: GEPA search budget
+- `reflection_model`: required when using GEPA
+
+## Using a Non-default Config
+
+`--config` is a global option and must appear before the subcommand:
+
+```bash
+codexopt --config codexopt.yaml benchmark
+codexopt --config codexopt.yaml optimize agents --file AGENTS.md
+```
+

docs/assets/codexopt_favicon.png

@@ -0,0 +1,38 @@
+# Demo Repository
+
+The companion demo repo is available here:
+
+- <https://github.com/SuperagenticAI/codexopt-demo>
+
+It contains:
+
+- a noisy and contradictory `AGENTS.md`
+- several intentionally messy `SKILL.md` files
+- `tasks.md` for task evidence
+- `issues.md` for recurring feedback themes
+
+## Why Use the Demo?
+
+The demo shows CodexOpt on a small repo where instruction problems are easy to see:
+
+- duplicate rules
+- contradiction
+- missing frontmatter
+- unnecessary verbosity
+
+## Typical Demo Flow
+
+```bash
+cd /path/to/codexopt-demo
+codexopt --config codexopt.gepa.example.yaml benchmark
+codexopt --config codexopt.gepa.example.yaml optimize agents --engine heuristic --file AGENTS.md
+codexopt --config codexopt.gepa.example.yaml optimize skills --engine heuristic --glob ".codex/skills/**/SKILL.md"
+codexopt --config codexopt.gepa.example.yaml report --output codexopt-report.md
+```
+
+## Cross-reference
+
+If you are reading the demo first, the main project lives here:
+
+- <https://github.com/SuperagenticAI/CodexOpt>
+