Add GitHub Pages site — landing + MkDocs docs (correct install instructions)

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: docs
+
+# Build the MkDocs site and deploy it to GitHub Pages.
+#
+# One-time manual step (cannot be automated from here):
+#   Repo Settings → Pages → Build and deployment → Source: "GitHub Actions".
+# After that, every push to main that touches the docs rebuilds and deploys to
+# https://fireflyframework.github.io/fireflyframework-agentic/
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress run.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+          restore-keys: ${{ runner.os }}-pip-
+      - name: Install docs toolchain
+        run: pip install -r docs/requirements.txt
+      - name: Build (strict)
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -144,3 +144,9 @@ examples/corpus_search/test_queries.md
 examples/corpus_search/test_queries.local.md
 docs/superpowers/
 PLAYGROUND.md
+
+# MkDocs build output
+/site/
+
+# Playwright MCP screenshots (local verification)
+/.playwright-mcp/

.pre-commit-config.yaml

@@ -34,6 +34,10 @@ repos:
         args: [--markdown-linebreak-ext=md]
       - id: end-of-file-fixer
       - id: check-yaml
+        # mkdocs.yml uses Material's `!!python/name:` tags (e.g. the mermaid
+        # superfence), which check-yaml can't construct. `mkdocs build --strict`
+        # in the docs workflow is its real validator.
+        exclude: ^mkdocs\.yml$
       - id: check-toml
       - id: check-json
         # tsconfig*.json files use JSONC (comments, trailing commas).

CHANGELOG.md

@@ -343,7 +343,7 @@ a **live Anthropic model** end to end. All nine confirmed P0/P1 findings address
 Framework alignment: the Dynamic Workflows engine and the tools system now run on
 the framework's own primitives and on pydantic-ai's native model — no parallel
 implementations, no lossy shims. Includes breaking changes; see the
-[Migration Guide](docs/migration.md).
+[Migration Guide](https://github.com/fireflyframework/fireflyframework-agentic/blob/main/docs/migration.md).
 
 ### Changed (BREAKING)
 

README.md

@@ -117,7 +117,7 @@ You write your business logic; the framework provides the architecture.
 ## Architecture at a Glance
 
 <p align="center">
-  <img src="assets/architecture.svg" alt="Firefly Agentic architecture: one front door (pip install fireflyframework-agentic, @firefly_agent) over five layers — Orchestration, Experimentation, Intelligence, Agent, Core — on the Pydantic AI engine." width="100%">
+  <img src="assets/architecture.svg" alt="Firefly Agentic architecture: one front door (import fireflyframework_agentic, @firefly_agent) over five layers — Orchestration, Experimentation, Intelligence, Agent, Core — on the Pydantic AI engine." width="100%">
 </p>
 
 ### Protocol Hierarchy

assets/tools/build_brand_assets.py

@@ -219,7 +219,7 @@ def architecture():
     b.append(f'<rect x="{X}" y="{fy}" width="{WD}" height="50" rx="12" fill="url(#door)" stroke="#6d28d9" stroke-width="1.2" filter="url(#sh)"/>')
     b.append(f'<rect x="{X+14}" y="{fy+6}" width="{WD-28}" height="2" rx="1" fill="#fbf8ff" opacity="0.3"/>')
     b.append(f'<text x="{X+22}" y="{fy+20}" font-size="10.5" font-weight="800" fill="#1c0e3a" letter-spacing="1.4">THE FRONT DOOR</text>')
-    b.append(f'<text x="{X+22}" y="{fy+39}" font-size="15" font-weight="800" fill="#190a35" font-family="{MONO}">pip install fireflyframework-agentic · @firefly_agent</text>')
+    b.append(f'<text x="{X+22}" y="{fy+39}" font-size="15" font-weight="800" fill="#190a35" font-family="{MONO}">import fireflyframework_agentic · @firefly_agent</text>')
     b.append(f'<text x="{X+WD-16}" y="{fy+20}" text-anchor="end" font-size="11" fill="#1c0e3a" font-weight="700">one install</text>')
     b.append(f'<text x="{X+WD-16}" y="{fy+39}" text-anchor="end" font-size="11" fill="#1c0e3a" font-weight="700">one decorator</text>')
     b.append(f'<g stroke="{VIOLET2}" stroke-width="1.4" stroke-dasharray="2 3" opacity="0.7">'+"".join(f'<line x1="{X+WD*f:.0f}" y1="{fy+50}" x2="{X+WD*f:.0f}" y2="170"/>' for f in (.18,.45,.72))+'</g>')

docs/agents.md

@@ -88,7 +88,7 @@ agent = FireflyAgent(name="analyst", model=model)
 ```
 
 This also works with the `@firefly_agent` decorator and all template agents. See the
-[tutorial](tutorial.md#model-providers--authentication) for full provider coverage
+[tutorial](tutorial.md#model-providers-authentication) for full provider coverage
 including Azure OpenAI, Anthropic, Google, and OpenAI-compatible endpoints.
 
 ### Model settings & default temperature
@@ -1153,4 +1153,4 @@ export OPENAI_API_KEY="sk-..."
 uv run python examples/basic_agent.py
 ```
 
-See [examples/README.md](../examples/README.md) for the full list.
+See [examples/README.md](https://github.com/fireflyframework/fireflyframework-agentic/blob/main/examples/README.md) for the full list.

docs/architecture.md

@@ -590,13 +590,13 @@ the framework adds on top is built to be provider-uniform:
   (those backends cache differently). See [Agents → PromptCacheMiddleware](agents.md#promptcachemiddleware).
 - **Tool schemas** — real `python_type`s keep tool schemas portable, with one
   caveat: **Gemini rejects free-form `dict[str, Any]` object schemas** — use a JSON
-  string or a nested model instead. See [Tools](tools.md#full-fidelity-schemas--runcontext).
+  string or a nested model instead. See [Tools](tools.md#full-fidelity-schemas-runcontext).
 - **Failover & rate limits** — `FallbackModelWrapper` / `run_with_fallback` fail over
   across providers, and rate-limit backoff prefers a provider's structured retry hint
   (e.g. Gemini `retry_delay`) before falling back to exponential backoff.
 
 This is validated end-to-end against a real provider by
-`tests/integration/test_real_anthropic_e2e.py` (nightly; see [tests/README](../tests/README.md)).
+`tests/integration/test_real_anthropic_e2e.py` (nightly; see [tests/README](https://github.com/fireflyframework/fireflyframework-agentic/blob/main/tests/README.md)).
 
 ---