diff --git a/.github/workflows/agent-readiness.yml b/.github/workflows/agent-readiness.yml new file mode 100644 index 0000000..5c6fa28 --- /dev/null +++ b/.github/workflows/agent-readiness.yml @@ -0,0 +1,56 @@ +name: Agent readiness + +# Weekly check of the live docs against the Agent-Friendly Documentation Spec. +# It runs on a schedule only, never on pull requests, so it can't block a PR. +on: + schedule: + - cron: "30 3 * * 1" # Mondays 03:30 UTC + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: agent-readiness + cancel-in-progress: true + +jobs: + afdocs: + name: AFDocs check of docs.graphify.com + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Run AFDocs + run: | + npx -y afdocs@0.23.0 check https://docs.graphify.com --format json --score -q > afdocs.json || true + npx -y afdocs@0.23.0 check https://docs.graphify.com --verbose -q > afdocs.txt 2>&1 || true + cat afdocs.txt + + - name: Upload results + if: always() + uses: actions/upload-artifact@v4 + with: + name: afdocs-${{ github.run_id }} + path: | + afdocs.json + afdocs.txt + retention-days: 90 + + - name: Fail on any failed check + run: | + python3 - <<'PY' + import json, sys + d = json.load(open("afdocs.json")) + s = d.get("summary", {}) + print(f"pass {s.get('pass')}, warn {s.get('warn')}, fail {s.get('fail')}, skip {s.get('skip')}, error {s.get('error')}") + failed = [r["id"] for r in d.get("results", []) if r.get("status") in ("fail", "error")] + for r in d.get("results", []): + if r.get("status") in ("fail", "error", "warn"): + level = "warning" if r["status"] == "warn" else "error" + print(f"::{level}::{r['id']}: {r.get('message', '')}") + sys.exit(1 if failed else 0) + PY diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 448e286..8ac6420 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,16 @@ Run both from the repo root, where `docs.json` lives. Each PR also gets a Mintli | Page icons | two icons repeat within one sidebar group, or a product-name page under `integrations/` has an `icon:` (a missing `icon:` elsewhere is only a warning) | | Mintlify broken links | `mint broken-links` finds a broken internal link | +## Agent readiness check + +`.github/workflows/agent-readiness.yml` runs [AFDocs](https://afdocs.dev) against https://docs.graphify.com every Monday and on demand from the Actions tab. It doesn't run on pull requests. Results are uploaded as a workflow artifact, and the run fails if any check fails. + +After a big change to the setup pages, also try these by hand in a fresh Claude Code session with no project memory, a few times each, and note which pages the agent fetched: + +- Set up Graphify in Claude Code starting only from https://docs.graphify.com/llms.txt. It should use the `claude mcp add` command from the docs and stop at sign-in. +- Install Graphify CLI. It should install the `graphifyy` package with uv or pipx. +- Ask which languages Graphify CLI supports for a given language. The answer should match `open-source/features/languages`. + ## Frontmatter ```yaml