diff --git a/.agents/skills/switchyard-docs-draft/SKILL.md b/.agents/skills/switchyard-docs-draft/SKILL.md new file mode 100644 index 00000000..8ac4bc2f --- /dev/null +++ b/.agents/skills/switchyard-docs-draft/SKILL.md @@ -0,0 +1,45 @@ +--- +name: switchyard-docs-draft +description: Draft net-new Switchyard documentation from repository evidence. Use when creating a new guide, tutorial, explanation, or reference page under docs/; not for polishing an existing page or reviewing examples only. +--- + +# Draft Switchyard Documentation + +Adapted from NVIDIA Tech Docs Skill Library's `doc-draft` workflow (Apache-2.0). + +Read `AGENTS.md` and `docs/AGENTS.md` completely before drafting. + +## Workflow + +1. Restate the requested document and identify its likely audience and Diataxis type: tutorial, + how-to, explanation, or reference. +2. Inspect the current documentation tree and `mkdocs.yml`. Decide whether to update an existing + page or create a public or internal page. +3. Enumerate evidence sources before writing: + - public source and configuration; + - CLI definitions or generated help; + - request and response schemas; + - tests and examples; + - related documentation. +4. Build a claim list. Include only claims supported by the inspected artifacts. Keep uncertain + claims out of published text and report them as maintainer questions. +5. Draft the shortest document that lets the target reader complete or understand the task. +6. Derive code examples from verified APIs and behavior. An example may compose public APIs into a + new runnable snippet, but every symbol, argument, flag, field, and default must be verified. +7. Integrate the page into `mkdocs.yml` as required by `docs/AGENTS.md`. +8. Run the strict docs build and report the evidence used, unresolved questions, and validation. + +## Drafting Rules + +- Front-load the outcome and prerequisites. +- Keep tutorials sequential, how-to guides task-oriented, explanations conceptual, and references + exhaustive within their declared scope. +- Prefer one complete example over several fragments. +- Label intentionally abbreviated examples or pseudocode. +- Do not publish speculative recommendations, performance claims, or unverified compatibility. +- Do not put source `file:line` annotations into reader-facing prose. + +## Handoff + +Report the created or updated paths, document type, principal evidence sources, unresolved questions, +and exact validation commands. Do not claim a live provider example was tested unless it was. diff --git a/.agents/skills/switchyard-docs-example-audit/SKILL.md b/.agents/skills/switchyard-docs-example-audit/SKILL.md new file mode 100644 index 00000000..2ce9055e --- /dev/null +++ b/.agents/skills/switchyard-docs-example-audit/SKILL.md @@ -0,0 +1,50 @@ +--- +name: switchyard-docs-example-audit +description: Audit Switchyard documentation examples against source code and schemas. Use when reviewing Python imports and call shapes, CLI commands and defaults, profile configuration, environment variables, or HTTP request and response examples. +--- + +# Audit Switchyard Documentation Examples + +Adapted from NVIDIA Tech Docs Skill Library's `doc-code-example-audit` workflow (Apache-2.0). + +Read `AGENTS.md` and `docs/AGENTS.md` completely. This is read-only unless the user also asks to fix +the findings. + +## Audit Checklist + +### Python + +- Verify imports use the canonical public package. +- Verify every referenced symbol exists and is publicly exported. +- Check constructor and method signatures against the current checkout. +- Mark illustrative types and pseudocode explicitly. + +### CLI + +- Read the owning parser definition or generated help. +- Check subcommand nesting, flag spelling, aliases, defaults, deprecations, and mutual exclusions. +- Confirm paths are interpreted as documented. + +### Configuration + +- Find the owning config model and loader. +- Check field names, nesting, accepted values, required fields, and defaults. +- Search other documentation for contradictory descriptions of the same field. + +### HTTP and JSON + +- Find the owning schema, wire type, translator, endpoint, and representative tests. +- Check field names, nesting, value types, and streaming versus non-streaming shape. +- Do not accept an example merely because it resembles an upstream provider format. + +### Environment and Providers + +- Confirm each environment variable is consumed by source. +- Verify precedence between explicit arguments, saved configuration, and environment fallbacks. +- Flag examples that imply credentials or live provider behavior without saying so. + +## Findings + +Report only verified mismatches. For each finding, include the documentation location, observed text, +authoritative source, user impact, and minimal correction. Separate confirmed defects from questions. +Say clearly when no material accuracy issues are found. diff --git a/.agents/skills/switchyard-docs-novice-review/SKILL.md b/.agents/skills/switchyard-docs-novice-review/SKILL.md new file mode 100644 index 00000000..c22d4555 --- /dev/null +++ b/.agents/skills/switchyard-docs-novice-review/SKILL.md @@ -0,0 +1,34 @@ +--- +name: switchyard-docs-novice-review +description: Review Switchyard documentation as a technically capable user who is new to the project. Use to find missing prerequisites, unexplained project terminology, incomplete setup steps, unclear success signals, and onboarding dead ends. +--- + +# Review Switchyard Documentation as a Newcomer + +Adapted from NVIDIA Tech Docs Skill Library's `doc-persona-novice` workflow (Apache-2.0). + +Read `AGENTS.md` and `docs/AGENTS.md` completely. Review without editing unless the user also asks +for fixes. + +Assume solid general software knowledge but no prior Switchyard knowledge. Understand APIs, CLIs, +LLMs, YAML, Git, and terminals; do not manufacture confusion about standard concepts. + +## Review Lenses + +1. **First contact:** Can the reader explain what the documented feature does, why it exists, and + when to use it? +2. **Prerequisites:** Are required packages, credentials, services, configuration, and platform + constraints stated before the first step? +3. **Sequence:** Can the reader move from one step to the next without an implied action? +4. **Success signals:** Does each important operation explain how to tell that it worked? +5. **Recovery:** Are likely failures actionable or linked to the right troubleshooting material? +6. **Project terminology:** Are Switchyard-specific terms defined at first use or linked clearly? +7. **Navigation:** Can the reader find the next relevant task without understanding the repository + layout? + +## Findings + +For each material issue, quote the smallest relevant passage, state where a capable newcomer gets +stuck, and propose the smallest correction. Distinguish project-specific jargon from normal +engineering terminology. End with an onboarding-readiness assessment and say clearly when no major +gaps are present. diff --git a/.agents/skills/switchyard-docs-polish/SKILL.md b/.agents/skills/switchyard-docs-polish/SKILL.md new file mode 100644 index 00000000..8a50c1b2 --- /dev/null +++ b/.agents/skills/switchyard-docs-polish/SKILL.md @@ -0,0 +1,43 @@ +--- +name: switchyard-docs-polish +description: Improve an existing Switchyard documentation page without changing its technical scope. Use when asked to polish, tighten, clarify, reorganize, or improve the readability of established Markdown content under docs/. +--- + +# Polish Switchyard Documentation + +Adapted from NVIDIA Tech Docs Skill Library's `doc-polish` workflow (Apache-2.0). + +Read `AGENTS.md` and `docs/AGENTS.md` completely before editing. Use this workflow only when the +page's foundation is sound; route missing or questionable technical content through +`switchyard-docs-example-audit` or a source-backed drafting pass first. + +## Workflow + +1. Identify the page's audience, purpose, and Diataxis type. +2. Preserve its technical scope and collect a small before-state assessment: + - Is the outcome visible early? + - Is the page scannable? + - Are prerequisites and next steps easy to find? + - Are examples complete enough for the intended audience? +3. Improve signal-to-noise. Remove repetition, filler, throat-clearing, and headings that do not + help navigation. Replace vague claims with concrete language without inventing facts. +4. Align the structure with the page type. Do not turn a reference into a tutorial or mix a long + conceptual explanation into a task procedure. +5. Apply progressive disclosure: essential path first, optional detail later, advanced material + behind a clear heading or supported disclosure element. +6. Improve headings, paragraphs, lists, terminology, and links. Use MkDocs features already enabled + in `mkdocs.yml`; do not introduce syntax from another documentation framework. +7. Review the diff and remove changes that are merely stylistic churn. +8. Run the strict docs build. + +## Boundaries + +- Do not alter documented behavior unless source evidence proves the old text wrong. +- Do not add features, examples, recommendations, or promises to make a page feel complete. +- Do not replace precise technical language with marketing language. +- Do not restructure neighboring pages unless the user asked for broader information architecture. + +## Handoff + +Summarize the material improvements, call out any accuracy questions left untouched, and report the +exact validation performed. diff --git a/.agents/skills/switchyard-docs-pragmatist-review/SKILL.md b/.agents/skills/switchyard-docs-pragmatist-review/SKILL.md new file mode 100644 index 00000000..1c289f5f --- /dev/null +++ b/.agents/skills/switchyard-docs-pragmatist-review/SKILL.md @@ -0,0 +1,35 @@ +--- +name: switchyard-docs-pragmatist-review +description: Review Switchyard documentation for copy-paste usability and scannability from a busy developer's perspective. Use to find incomplete commands, non-runnable examples, buried prerequisites, missing expected output, and avoidable task friction. +--- + +# Review Switchyard Documentation for Task Usability + +Adapted from NVIDIA Tech Docs Skill Library's `doc-persona-pragmatist` workflow (Apache-2.0). + +Read `AGENTS.md` and `docs/AGENTS.md` completely. Review without editing unless the user also asks +for fixes. + +Assume an experienced engineer with a deadline who scans headings and examples before reading long +explanations. + +## Review Lenses + +1. **Copy-paste path:** Check whether commands and code blocks are complete in their stated context. +2. **Setup:** Find missing imports, variables, files, credentials, working-directory assumptions, + and prerequisite commands. +3. **Scannability:** Confirm the primary command or example appears before optional detail and under + a heading a task-oriented reader would recognize. +4. **Expected result:** Check whether the reader can tell that each key step succeeded. +5. **Failure path:** Check whether common errors have an immediate fix or a precise link. +6. **End-to-end completeness:** Prefer one complete runnable path over fragments that require the + reader to assemble hidden context. + +Do not demand that every conceptual page become a quickstart. Judge the page against its declared +purpose and audience. + +## Findings + +For each material issue, identify the location, explain the concrete failure or friction, and propose +the smallest fix. Separate confirmed runnability failures from untested concerns. End with an +estimated time-to-first-success assessment and say clearly when the page is ready for a busy reader. diff --git a/.agents/skills/switchyard-docs/SKILL.md b/.agents/skills/switchyard-docs/SKILL.md deleted file mode 100644 index 6b99df8c..00000000 --- a/.agents/skills/switchyard-docs/SKILL.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -name: switchyard-docs -description: Use when adding or editing pages on the published Switchyard MkDocs site (`docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`), wiring a new page into the nav, debugging a `mkdocs build --strict` failure, previewing the site locally, or reviewing changes to the docs CI workflow. Triggers on phrases like "add a docs page", "the docs site is broken", "mkdocs strict is failing", "preview docs locally", or any edit under `docs/**` that should reach the published Pages site. ---- - -# Switchyard Docs Site - -## Overview - -**The published site is a deliberately small subset of `docs/`.** Most files under `docs/` are internal design notes; only the pages listed in `mkdocs.yml`'s `nav:` (and not in `exclude_docs`) ship to the public site. When in doubt, prefer not to publish — add a file as internal first, then promote it once the content is stable. - -**Strict mode is the contract.** `mkdocs build --strict` runs in CI (`.github/workflows/docs.yml`) and locally via `make publish`. Any warning — missing link target, unrecognized anchor, ambiguous file reference — fails the build. If you broke strict, fix the warning rather than relaxing the gate. - -Repository files outside `docs_dir` are linked with paths relative to the Markdown source. The -`mkdocs_hooks.py` `on_page_markdown` hook rewrites valid in-repository targets to source URLs using -`repo_url` and `extra.source_ref` from `mkdocs.yml` before MkDocs validates links. The source ref -comes from `MKDOCS_SOURCE_REF`, with `main` as the local fallback. CI sets it to the PR head SHA or -push SHA so preview and published links resolve against the exact source commit. Missing targets and -paths that escape the repository remain relative so strict validation still exposes them. - -The docs site uses the same `uv` toolchain as the rest of the repo. Dependencies live in the `docs` group in `pyproject.toml`; there is no separate `requirements*.txt`. - -## Quick Reference - -| Situation | Command | -|---|---| -| Sync the docs dependency group | `cd docs && make env` (= `uv sync --only-group docs`) | -| Live-reload preview at http://127.0.0.1:8000 | `cd docs && make live` | -| One-shot strict build (mirrors CI) | `cd docs && make publish` | -| Plain incremental build | `cd docs && make html` | -| Remove `site/` | `cd docs && make clean` | -| List published pages | `grep -A20 "^nav:" mkdocs.yml` | -| List excluded `docs/*.md` | `grep -A10 "^exclude_docs:" mkdocs.yml` | - -The MkDocs config and the workflow live at the repo root; `docs/Makefile` cd's there for you. - -## Where Things Live - -Before editing, discover the current state — don't memorize it: - -- **Published page set** → `nav:` block in `mkdocs.yml`. The order there is the order on the site. -- **Hidden-from-publish files** → `exclude_docs:` block in `mkdocs.yml`. Anything under `docs/` that isn't in `nav:` and isn't excluded will trigger a strict-build warning. -- **Internal design notes** → also under `docs/`, but excluded. They live next to published pages so cross-linking from internal notes to public pages stays trivial. -- **Build/preview entry points** → `docs/Makefile` (thin wrapper over `uv run --only-group docs mkdocs ...`). -- **Docs dependencies** → `docs` group in `pyproject.toml`; resolved into `uv.lock` like the rest of the project. -- **Site styling** → `docs/stylesheets/` (extra CSS) and the `theme:` block in `mkdocs.yml`. -- **Repository source-link hook** → `mkdocs_hooks.py`, configured by `repo_url` and - `extra.source_ref` in `mkdocs.yml`. `MKDOCS_SOURCE_REF` overrides the local `main` fallback. -- **CI** → `.github/workflows/docs.yml`. Triggered on `docs/**`, `mkdocs_hooks.py`, `mkdocs.yml`, - `pyproject.toml`, `uv.lock`, and the workflow file itself. - -Run `ls docs/` and `grep -A20 "^nav:" mkdocs.yml` to see the current set in one shot. - -## Adding a Page - -1. **Decide whether it's public or internal.** Internal design notes stay out of `nav` and go into `exclude_docs`. Don't ship anything that isn't stable enough to read cold. -2. **Place the file under `docs/`.** Use existing naming: lower_snake or UPPER_SNAKE — match the surrounding pages on the same topic. -3. **Wire it into `mkdocs.yml`** in two places: - - Add the entry under `nav:` with a human-readable title. - - Remove it from `exclude_docs` if a stale entry exists. -4. **Use relative links between published pages** (e.g. `[Architecture](architecture.md)`). MkDocs strict mode resolves these against `docs_dir`. -5. **Link to repository files outside `docs_dir` relative to the Markdown file.** For example, - `docs/operations/example.md` links to `examples/config.yaml` as - `../../examples/config.yaml`. The source-link hook turns an existing in-repository file into a - `/blob//...` URL and a directory into `/tree//...` during the build. -6. **Run `make publish` locally** before pushing. CI runs `mkdocs build --strict`; reproduce that locally. -7. **Code samples in docs are tested by reading.** They are not executed by CI, so the burden is on the author. Verify imports resolve from `switchyard/__init__.py`'s `__all__` (anything else is an internal path that may move). -8. **Provider examples must match CLI resolution.** NVIDIA examples may use `NVIDIA_API_KEY` where the CLI supports that fallback. OpenRouter examples should use `https://openrouter.ai/api/v1` and pass `"$OPENROUTER_API_KEY"` via `--api-key`, or save it with `switchyard configure --provider openrouter`, unless the code being documented actually adds an `OPENROUTER_API_KEY` fallback. - -## CI Hygiene - -`.github/workflows/docs.yml` mirrors the conventions in `ci.yml` — match them when editing: - -- **Path-filtered triggers** on `docs/**`, `mkdocs_hooks.py`, `mkdocs.yml`, `pyproject.toml`, - `uv.lock`, and the workflow file. Keeps unrelated PRs out of the docs job graph. -- **Read-only default permissions** at the workflow level. Each job re-declares write scopes only when it needs them (`contents: write` for the Pages deploy, `pull-requests: write` for the preview comment). -- **`concurrency` group `${{ github.workflow }}-${{ github.ref }}`** with `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`. Superseded PR runs are cancelled; main runs queue so the `gh-pages` writes don't race. -- **Workflow-level `MKDOCS_SOURCE_REF`** resolves from - `${{ github.event.pull_request.head.sha || github.sha }}`. Pull requests use the immutable head - commit; pushes use the pushed commit. Keep this environment override on both build event types. -- **`astral-sh/setup-uv@v6`** with `enable-cache: true` and `cache-dependency-glob: "uv.lock"`. Cache is keyed off the same lockfile the rest of the project uses. -- **`uv sync --only-group docs --locked`** installs just the docs group, deterministically. -- **`uv run --only-group docs mkdocs build --strict`** is the build step. The local equivalent is `make publish`. -- **Preview job gated to same-repo PRs.** `GITHUB_TOKEN` from a fork PR has no write scope on `gh-pages`, so the `if:` clause checks `head.repo.full_name == github.repository`. Don't switch to `pull_request_target` to "fix" this — that runs untrusted PR code with write secrets. -- **Single artifact handoff between jobs.** The `build` job uploads `site/`; `deploy` and `preview` download it. Don't duplicate the build inside either downstream job — it diverges from what was validated. - -If the workflow needs a new job (e.g. link check, spell check), keep it inside this file and gate it on the same path filter so it doesn't fan out to unrelated PRs. - -## Failure → Fix Map - -| Symptom | Fix | -|---|---| -| `WARNING - A reference to 'X.md' is included in the 'nav' configuration ... is not found in the documentation files` | The nav points at a file that doesn't exist under `docs/`. Add the file or drop the nav entry. | -| `WARNING - Doc file 'X.md' contains a link 'Y.md', but the doc does not exist` | Bad relative link. Use a path relative to the Markdown file. Existing targets outside `docs_dir` are rewritten by `mkdocs_hooks.py`; missing and repository-escaping paths intentionally remain visible to strict validation. | -| `WARNING - Doc file 'X.md' is excluded from the build but its 'nav' entry references it` | The file is both in `nav:` and in `exclude_docs:`. Pick one. | -| `WARNING - The following pages exist in the docs directory, but are not included in the "nav" configuration` | Either add the page to `nav:` (publish it) or add it to `exclude_docs:` (hide it). The "do nothing" option doesn't exist under strict. | -| Repository links in a PR preview point at `main` | Confirm `MKDOCS_SOURCE_REF` is present in the build job and resolves to `github.event.pull_request.head.sha`; local builds intentionally fall back to `main`. | -| Preview job fails with `Permission to .git denied to github-actions[bot]` on a fork PR | Expected — the preview job is gated to same-repo PRs. If the gate is firing on a same-repo PR, check that `github.event.pull_request.head.repo.full_name` resolves correctly. | -| GitHub Pages site loses PR previews after a `main` deploy | Confirm `keep_files: true` on the `peaceiris/actions-gh-pages` step. The main deploy must not wipe `pr-preview/*`. | -| `make env` fails with `uv: command not found` | Install `uv` per the project Setup docs (see `AGENTS.md`). The Makefile shells out to `uv`; no separate Python toolchain is bootstrapped. | - -## Anti-Patterns - -- **Publishing internal design notes.** Anything under `docs/` that isn't a user-facing walkthrough or reference belongs in `exclude_docs`, not in `nav:`. Internal notes drift faster than the public surface and confuse users who land on them from search. -- **Hard-coded same-repository GitHub blob/tree URLs.** They pin the repository and source ref, - which breaks forks and branch-specific builds. Use a path relative to the Markdown file and let - `mkdocs_hooks.py` derive the source URL from `mkdocs.yml`. -- **Disabling `strict: true`** to make a CI failure go away. The warning is the bug. The two legitimate fixes are: fix the broken reference, or add the file to `exclude_docs`. -- **Importing internal symbols in published examples.** Code in published pages must import from `switchyard` (the public API), not from `switchyard.lib.*` or any other internal path. Anything outside `switchyard/__init__.__all__` can move without a deprecation. -- **Reintroducing a separate `requirements-mkdocs.txt`.** Docs deps belong in the `docs` group in `pyproject.toml` so `uv.lock` is the single source of pinned versions. Two pinning surfaces drift. -- **Switching the preview job to `pull_request_target`** to make fork previews work. That trades a missing preview for a real supply-chain risk. The current `if:` gate is the right answer. - -## References - -- `mkdocs.yml` — published-site config -- `mkdocs_hooks.py` — repository-relative source-link rewriting -- `docs/README.md` — local build instructions -- `docs/Makefile` — `env / html / publish / live / clean` -- `.github/workflows/docs.yml` — build + deploy + preview pipeline -- `pyproject.toml` — `[dependency-groups]` `docs = [...]` -- [`switchyard-testing-ci`](../switchyard-testing-ci/SKILL.md) — broader CI/validation guidance (ruff, mypy, pytest gates) -- [`switchyard-codebase-exploration`](../switchyard-codebase-exploration/SKILL.md) — load before editing docs that cite specific symbols, file paths, or APIs diff --git a/AGENTS.md b/AGENTS.md index 3a9f7253..c7223241 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,14 @@ Two general-purpose entry points cover most tasks: - `.agents/skills/switchyard-testing-ci/SKILL.md` — picks the smallest trustworthy local validation set and maps failures to fixes. - `.agents/skills/switchyard-pr-reviewer/SKILL.md` — multi-mode PR-review workflow (correctness, tests, design-vs-ticket, simplify, docs, Rust-craft); adversarially verifies every finding and drafts comments before posting. Dispatches Rust to `rust-code-reviewer`. Use for any "review this PR / is this blocking? / post comments" request. +Documentation work uses the scoped rules in `docs/AGENTS.md` plus the matching workflow skill: + +- `.agents/skills/switchyard-docs-draft/SKILL.md` — evidence-backed drafting. +- `.agents/skills/switchyard-docs-polish/SKILL.md` — focused revision of existing pages. +- `.agents/skills/switchyard-docs-example-audit/SKILL.md` — code, CLI, payload, and config example accuracy. +- `.agents/skills/switchyard-docs-novice-review/SKILL.md` — onboarding review from a capable newcomer’s perspective. +- `.agents/skills/switchyard-docs-pragmatist-review/SKILL.md` — copy-paste usability and scannability review. + Task-specific skills (publish-package, run-pre-merge-checks, etc.) live alongside them — scan the directory and read the SKILL.md of any whose `description` matches the task. If no skill applies, say so explicitly and proceed; do not silently skip discovery. ### Keep skills in sync with the code they cover diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 00000000..ecbaf392 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,72 @@ +# Switchyard Documentation + +These instructions apply to all files under `docs/`. Read the repository-level `AGENTS.md` first, +then load the documentation workflow skill that matches the task. + +## Published Site Contract + +The published site is a deliberately small subset of `docs/`. Pages listed under `nav:` in +`mkdocs.yml` are public. Internal design notes belong under an `exclude_docs` pattern. Do not leave +a page in neither set: strict MkDocs treats that as a warning and fails the build. + +`mkdocs build --strict` is the contract. Fix warnings instead of weakening strict mode. + +Repository files outside `docs_dir` must use paths relative to the Markdown source. The +`mkdocs_hooks.py` hook rewrites valid in-repository targets to source URLs using `repo_url` and +`extra.source_ref`. `MKDOCS_SOURCE_REF` selects the source revision; local builds default to `main`. + +The docs dependencies live in the `docs` dependency group in `pyproject.toml`. Do not add a +separate requirements file. + +## Commands + +| Situation | Command | +|---|---| +| Sync docs dependencies | `cd docs && make env` | +| Strict build matching CI | `cd docs && make publish` | +| Incremental build | `cd docs && make html` | +| Live preview | `cd docs && make live` | +| Remove generated site | `cd docs && make clean` | + +## Adding or Publishing a Page + +1. Decide whether the page is public or internal. +2. Put the file under `docs/` using the naming pattern of neighboring pages. +3. Add a public page to `nav:` in `mkdocs.yml`, or cover an internal page with `exclude_docs`. +4. Use relative links between documentation pages. +5. Link to repository files outside `docs/` relative to the Markdown file; let + `mkdocs_hooks.py` create the source URL. +6. Run `cd docs && make publish` before handing off the change. + +## Accuracy Rules + +- Ground behavioral claims in source, configuration, schemas, tests, or command output from the + current checkout. Omit or flag claims that cannot be verified. +- Published Python examples import from `switchyard`, not `switchyard.lib.*`. Confirm every public + symbol appears in `switchyard/__init__.py`'s `__all__`. +- Verify CLI flags, defaults, nesting, and deprecations against the parser before publishing them. +- Verify configuration and payload examples against their owning model, loader, translator, or + endpoint tests. +- NVIDIA examples may use `NVIDIA_API_KEY` where the CLI supports that fallback. OpenRouter + examples use `https://openrouter.ai/api/v1` and pass `"$OPENROUTER_API_KEY"` through `--api-key`, + or save it with `switchyard configure --provider openrouter`, unless source proves a different + resolution path. +- Keep evidence in the handoff or review report, not as `file:line` annotations in published prose. + +## CI and Security Boundaries + +- Keep docs CI path-filtered to documentation inputs. +- Preserve read-only workflow permissions except where a job explicitly needs write access. +- Keep PR previews limited to same-repository PRs. Do not use `pull_request_target` to run + untrusted documentation changes with write credentials. +- Preserve `MKDOCS_SOURCE_REF` so previews link to the reviewed commit. +- Build the site once and hand the same artifact to preview and deployment jobs. + +## Anti-Patterns + +- Publishing internal design notes as user documentation. +- Hard-coding same-repository GitHub blob or tree URLs. +- Disabling strict mode to hide a warning. +- Publishing examples that import internal modules or contain unverified flags and defaults. +- Editing generated site output or a generated docs environment. +- Adding a second docs dependency file outside `pyproject.toml` and `uv.lock`. diff --git a/mkdocs.yml b/mkdocs.yml index 537c1af6..2ded1ada 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,6 +39,7 @@ nav: - CLI Reference: cli_reference.md exclude_docs: | + AGENTS.md internal/** research/** local_models.md