Merge branch 'main' into rachaelrenk/aeo-citation-blocks

Author: rachaelrenk

.agents/skills/missing_docs/references/feature_surface_map.md

@@ -137,17 +137,22 @@ SkillArguments -> src/content/docs/agent-platform/warp-agents/skills.md
 ## CLI commands -> doc pages
 
 # Top-level Oz CLI commands
-oz agent -> src/content/docs/reference/cli/README.md
-oz environment -> src/content/docs/reference/cli/integration-setup.md
-oz mcp -> src/content/docs/reference/cli/mcp-servers.md
-oz run -> src/content/docs/reference/cli/README.md
-oz model -> src/content/docs/reference/cli/README.md
-oz login -> src/content/docs/reference/cli/README.md
-oz logout -> src/content/docs/reference/cli/README.md
-oz integration -> src/content/docs/reference/cli/integration-setup.md
-oz schedule -> src/content/docs/reference/cli/README.md
-oz secret -> src/content/docs/reference/cli/README.md
-oz provider -> src/content/docs/reference/cli/README.md
+oz agent -> src/content/docs/reference/cli/index.mdx
+oz environment -> src/content/docs/reference/cli/integration-setup.mdx
+oz mcp -> src/content/docs/reference/cli/mcp-servers.mdx
+oz run -> src/content/docs/reference/cli/index.mdx
+oz model -> src/content/docs/reference/cli/index.mdx
+oz login -> src/content/docs/reference/cli/index.mdx
+oz logout -> src/content/docs/reference/cli/index.mdx
+oz whoami -> src/content/docs/reference/cli/index.mdx
+oz integration -> src/content/docs/reference/cli/integration-setup.mdx
+oz schedule -> src/content/docs/reference/cli/index.mdx
+oz secret -> src/content/docs/reference/cli/index.mdx
+oz provider -> src/content/docs/reference/cli/index.mdx
+oz federate -> src/content/docs/reference/cli/federate.mdx
+oz artifact -> src/content/docs/reference/cli/artifacts.mdx
+# Internal/hidden command — not a user-facing surface, so no public docs.
+oz harness-support -> internal
 
 ## API endpoints -> doc pages
 

.agents/skills/missing_docs/scripts/audit_docs.py

@@ -24,6 +24,9 @@
 
 SKIP_DIRECTORIES = {"_book", "node_modules", ".git", ".docs"}
 
+# Mutable holder for the docs repo root, set by main()
+DOCS_REPO_ROOT: list = [None]
+
 # Paths to reference files (relative to this script)
 SCRIPT_DIR = Path(__file__).resolve().parent
 SKILL_DIR = SCRIPT_DIR.parent
@@ -179,13 +182,17 @@ def search_docs_for_terms(docs_text: dict[str, str], terms: list[str]) -> list[s
 
 def parse_feature_flags(warp_internal: Path) -> list[str]:
     """Parse FeatureFlag enum variants from features.rs."""
-    # The FeatureFlag enum lives in the warp_features crate
-    features_rs = warp_internal / "crates" / "warp_features" / "src" / "lib.rs"
-    if not features_rs.exists():
-        # Fall back to legacy path
-        features_rs = warp_internal / "warp_core" / "src" / "features.rs"
-    if not features_rs.exists():
-        print(f"Warning: {features_rs} not found", file=sys.stderr)
+    # Try known locations in order
+    candidates = [
+        warp_internal / "crates" / "warp_features" / "src" / "lib.rs",
+        warp_internal / "crates" / "warp_core" / "src" / "features.rs",
+        warp_internal / "app" / "src" / "features.rs",
+        warp_internal / "warp_core" / "src" / "features.rs",
+    ]
+    features_rs = next((c for c in candidates if c.exists()), None)
+    if features_rs is None:
+        print(f"Warning: features.rs not found. Tried: {[str(c) for c in candidates]}",
+              file=sys.stderr)
         return []
 
     content = features_rs.read_text()
@@ -213,9 +220,14 @@ def parse_feature_flags(warp_internal: Path) -> list[str]:
 
 def parse_default_features(warp_internal: Path) -> set[str]:
     """Parse the default feature list from app/Cargo.toml."""
-    cargo_toml = warp_internal / "app" / "Cargo.toml"
-    if not cargo_toml.exists():
-        print(f"Warning: {cargo_toml} not found", file=sys.stderr)
+    candidates = [
+        warp_internal / "app" / "Cargo.toml",
+        warp_internal / "crates" / "warp_features" / "Cargo.toml",
+    ]
+    cargo_toml = next((c for c in candidates if c.exists()), None)
+    if cargo_toml is None:
+        print(f"Warning: app/Cargo.toml not found. Tried: {[str(c) for c in candidates]}",
+              file=sys.stderr)
         return set()
 
     content = cargo_toml.read_text()
@@ -292,8 +304,14 @@ def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict,
 
 def parse_cli_commands(warp_internal: Path) -> list[dict]:
     """Parse CLI subcommands from warp_cli/src/lib.rs."""
-    lib_rs = warp_internal / "warp_cli" / "src" / "lib.rs"
-    if not lib_rs.exists():
+    candidates = [
+        warp_internal / "crates" / "warp_cli" / "src" / "lib.rs",
+        warp_internal / "warp_cli" / "src" / "lib.rs",
+    ]
+    lib_rs = next((c for c in candidates if c.exists()), None)
+    if lib_rs is None:
+        print(f"Warning: warp_cli/src/lib.rs not found. Tried: {[str(c) for c in candidates]}",
+              file=sys.stderr)
         return []
 
     content = lib_rs.read_text()
@@ -329,8 +347,12 @@ def parse_cli_commands(warp_internal: Path) -> list[dict]:
 
 def parse_subcommands_from_file(warp_internal: Path, filename: str) -> list[str]:
     """Parse subcommand names from a CLI command file (e.g., agent.rs)."""
-    filepath = warp_internal / "warp_cli" / "src" / filename
-    if not filepath.exists():
+    candidates = [
+        warp_internal / "crates" / "warp_cli" / "src" / filename,
+        warp_internal / "warp_cli" / "src" / filename,
+    ]
+    filepath = next((c for c in candidates if c.exists()), None)
+    if filepath is None:
         return []
 
     content = filepath.read_text()
@@ -366,6 +388,10 @@ def audit_cli(warp_internal: Path, docs_root: Path, surface_map: dict,
         # Check surface map
         if cmd_str in cli_to_doc:
             doc_path = cli_to_doc[cmd_str]
+            # `internal` is a sentinel for hidden/internal commands that
+            # intentionally have no public docs (matches API audit semantics).
+            if doc_path == "internal":
+                continue
             if (docs_root.parent / doc_path).exists():
                 continue  # Mapped and exists
 
@@ -437,8 +463,13 @@ def audit_api(warp_server: Path, docs_root: Path, surface_map: dict,
             except Exception:
                 pass
 
-    # Also check OpenAPI spec
-    openapi_path = docs_root / "developers" / "agent-api-openapi.yaml"
+    # Also check OpenAPI spec (lives at repo root, not under content/docs)
+    repo_root = DOCS_REPO_ROOT[0] or docs_root.parent
+    openapi_candidates = [
+        repo_root / "developers" / "agent-api-openapi.yaml",
+        docs_root / "developers" / "agent-api-openapi.yaml",
+    ]
+    openapi_path = next((c for c in openapi_candidates if c.exists()), openapi_candidates[0])
     openapi_text = ""
     if openapi_path.exists():
         try:
@@ -640,12 +671,20 @@ def main():
     args = parser.parse_args()
 
     # Find repos
-    docs_root = SKILL_DIR.parent.parent.parent  # .warp/skills/missing_docs -> docs root
-    docs_root = docs_root / "docs"
-
-    if not docs_root.exists():
-        print(f"Error: docs directory not found at {docs_root}", file=sys.stderr)
+    # SKILL_DIR is at <repo>/.agents/skills/missing_docs (or legacy <repo>/.warp/skills/...)
+    repo_root = SKILL_DIR.parent.parent.parent
+    # Astro Starlight docs live at src/content/docs
+    candidates = [
+        repo_root / "src" / "content" / "docs",
+        repo_root / "docs",
+    ]
+    docs_root = next((c for c in candidates if c.exists()), None)
+    if docs_root is None:
+        print(f"Error: docs directory not found. Tried: {[str(c) for c in candidates]}",
+              file=sys.stderr)
         sys.exit(1)
+    # repo_root carries the developers/ openapi spec etc.
+    DOCS_REPO_ROOT[0] = repo_root
 
     warp_internal = find_repo("warp-internal", args.warp_internal, docs_root)
     warp_server = find_repo("warp-server", args.warp_server, docs_root)

.agents/skills/style_lint/style_lint.py

@@ -24,7 +24,11 @@
 # Configuration
 # ---------------------------------------------------------------------------
 
-DOCS_ROOT = Path("docs")
+# Astro Starlight content lives under src/content/docs/, not a top-level docs/.
+# This used to be `Path("docs")`, which silently scanned 0 files in the
+# Astro layout — running --all reported "No issues found" without auditing
+# anything.
+DOCS_ROOT = Path("src/content/docs")
 CHANGELOG_DIR = DOCS_ROOT / "changelog"
 EXCLUDED_DIRS = {"_book", "node_modules", ".docs"}
 
@@ -134,7 +138,7 @@ class Report:
 def find_all_md_files() -> List[Path]:
     """Find all markdown files in docs/, excluding build artifacts and changelog."""
     files = []
-    for f in DOCS_ROOT.rglob("*.md"):
+    for f in [*DOCS_ROOT.rglob("*.md"), *DOCS_ROOT.rglob("*.mdx")]:
         if any(part in EXCLUDED_DIRS for part in f.parts):
             continue
         # Exclude changelog (historical record)
@@ -148,12 +152,12 @@ def find_changed_md_files() -> List[Path]:
     """Find markdown files changed in the current branch vs main."""
     try:
         result = subprocess.run(
-            ["git", "diff", "--name-only", "origin/main...HEAD", "--", "docs/"],
+            ["git", "diff", "--name-only", "origin/main...HEAD", "--", str(DOCS_ROOT)],
             capture_output=True, text=True, check=True,
         )
         files = []
         for line in result.stdout.strip().split("\n"):
-            if line.endswith(".md") and os.path.exists(line):
+            if (line.endswith(".md") or line.endswith(".mdx")) and os.path.exists(line):
                 p = Path(line)
                 if not any(part in EXCLUDED_DIRS for part in p.parts):
                     files.append(p)
@@ -658,7 +662,7 @@ def create_pr_with_fixes() -> None:
     """Create a branch and PR with the auto-fixes."""
     branch = "fix/style-lint-auto-fixes"
     subprocess.run(["git", "checkout", "-b", branch], check=True)
-    subprocess.run(["git", "add", "docs/"], check=True)
+    subprocess.run(["git", "add", str(DOCS_ROOT)], check=True)
     result = subprocess.run(["git", "diff", "--cached", "--quiet"])
     if result.returncode == 0:
         print("No changes to commit.")

.agents/skills/sync-openapi-spec/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: sync-openapi-spec
+description: >-
+  Sync the public Oz Agent API OpenAPI spec from warp-server into the docs
+  repo, regenerating `developers/agent-api-openapi.yaml` (the file that
+  powers the Scalar API reference at `docs.warp.dev/api`). Use when the
+  warp-server public API has changed, when the Scalar reference looks
+  stale, or on a scheduled cadence to keep the public API docs aligned
+  with the canonical spec.
+---
+
+# Sync OpenAPI Spec
+
+Keep `developers/agent-api-openapi.yaml` in sync with the canonical spec at `warp-server/public_api/openapi.yaml`.
+
+**Direction:** warp-server → docs. The server spec is the source of truth. The docs file is a curated subset (drops `memory_stores`/`harness-support` and a handful of internal `agent` paths) that Scalar renders on `docs.warp.dev/api`.
+
+## Repos
+
+This skill requires two repos in the agent's environment:
+
+- `warpdotdev/warp-server` — source of truth (`public_api/openapi.yaml`)
+- `warpdotdev/docs` — Scalar-facing copy (`developers/agent-api-openapi.yaml`)
+
+## Prerequisites
+
+- Both repos checked out, with `warp-server` reachable from the docs repo (default assumption: sibling directories — `../warp-server/public_api/openapi.yaml`)
+- Python 3 with `pyyaml` installed (`pip install pyyaml` or `pip install --break-system-packages pyyaml` in managed environments)
+- `gh` CLI authenticated against `warpdotdev/docs`
+
+## Workflow
+
+### Step 1: Self-test
+
+Run the script's self-test first to confirm `pyyaml` is available and the transform logic still passes:
+
+```bash
+python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py --mode self-test
+```
+
+Expected output: `self-test: OK`. If this fails, fix the script before going further.
+
+### Step 2: Diff source against target
+
+```bash
+python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py \
+  --mode diff \
+  --source ../warp-server/public_api/openapi.yaml \
+  --target developers/agent-api-openapi.yaml
+```
+
+The script prints structural drift grouped into:
+- Paths added/removed/modified relative to the expected docs subset
+- Component schemas added/removed/modified
+- Top-level changes (`openapi`, `info`, `servers`)
+- Unclassified tags or paths (anything not covered by `EXCLUDED_TAGS` or the `agent`/`schedules` allowlist)
+
+If the script reports `In sync. No changes needed.`, stop here.
+
+### Step 3: Triage unclassified items
+
+Any line prefixed with `!` flags a tag or path the policy doesn't recognize. Do NOT auto-include or auto-drop these. For each one:
+1. Read the corresponding handler in `warp-server/router/handlers/public_api/` to confirm whether the endpoint is intended to be public.
+2. If the endpoint is public-facing, leave the policy alone — the script will include it on the next `apply`.
+3. If the endpoint should remain hidden, extend `EXCLUDED_TAGS` or `EXCLUDED_PATHS` in `scripts/sync_openapi.py` and update `references/sync-policy.md` to record the rationale.
+4. Re-run `--mode diff` until no `!` lines remain.
+
+### Step 4: Apply the regenerated subset
+
+```bash
+python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py \
+  --mode apply \
+  --source ../warp-server/public_api/openapi.yaml \
+  --target developers/agent-api-openapi.yaml
+```
+
+This rewrites `developers/agent-api-openapi.yaml` with the regenerated subset. Apply mode validates every `$ref` in the output before writing the file: if any reference is unresolved, the script exits with code 3 and refuses to write. On success it prints `All $refs resolve in the regenerated spec.`
+
+### Step 5: Validate the regenerated spec
+
+Apply mode already catches unresolved `$ref`s (see Step 4). Run these as belt-and-braces integration checks:
+
+```bash
+# Astro picks up the new YAML and parses it through Scalar's runtime.
+npm run build
+```
+
+Optional, recommended when many schemas changed (full OpenAPI lint):
+```bash
+npx @redocly/cli lint developers/agent-api-openapi.yaml
+```
+
+If `npm run build` fails, the most common cause is a malformed path or missing `description` field. Schema-ref breakage is already prevented by Step 4's validator.
+
+### Step 6: Commit and open a PR
+
+```bash
+git checkout -b sync-openapi-spec/YYYY-MM-DD
+git add developers/agent-api-openapi.yaml
+git commit -m "docs: sync agent-api-openapi.yaml from warp-server
+
+Co-Authored-By: Oz <oz-agent@warp.dev>"
+git push origin sync-openapi-spec/YYYY-MM-DD
+```
+
+Open a draft PR with:
+- **Title:** `docs: sync agent-api-openapi.yaml from warp-server`
+- **Body:** include the full output from Step 2 (paths/schemas added/removed/modified) so reviewers can see exactly what changed and why.
+- **Labels:** `documentation`
+
+Use `report_pr` to surface the PR link.
+
+### Step 7: Report
+
+Summarize:
+- Source commit SHA used (capture with `cd ../warp-server && git rev-parse HEAD`)
+- Number of paths added / removed / modified in the regenerated subset
+- Number of schemas added / removed / modified
+- Any items flagged for triage and how they were resolved
+- Or confirm `In sync. No changes needed.`
+
+## Sync policy
+
+The policy is encoded in `scripts/sync_openapi.py` as `EXCLUDED_TAGS` and `EXCLUDED_PATHS`. See `references/sync-policy.md` for the rationale behind each entry and the rules for adding new ones.
+
+## Schedule
+
+Run on demand whenever `warp-server/public_api/openapi.yaml` has changed materially since the last docs sync, or on a weekly cadence as a safety net.
+
+## Troubleshooting
+
+### `ModuleNotFoundError: No module named 'yaml'`
+Install pyyaml: `pip install pyyaml`. On Debian-based images with externally managed Python, use `pip install --break-system-packages pyyaml`.
+
+### `error: source spec not found at ...`
+The `warp-server` repo isn't where the script expected. Pass `--source /absolute/path/to/warp-server/public_api/openapi.yaml`.
+
+### `--mode apply` exits with code 3 and "unresolved $refs"
+Apply mode refuses to write the target if any `$ref` in the regenerated spec doesn't resolve to a defined component. The script's recursive `$ref` walker is supposed to keep transitive references (`allOf`/`oneOf`/`anyOf`/`items`/`additionalProperties`/etc.) reachable, so this means either:
+- The source spec itself has a dangling reference (fix it in `warp-server`), or
+- The walker is missing a reference shape (file a bug against the script).
+
+The error output lists the offending JSON pointer paths so you can locate the reference quickly. Apply will not overwrite `developers/agent-api-openapi.yaml` while this fails.
+
+### Diff shows changes that aren't in the source spec
+Make sure `../warp-server` is on the branch you intended to compare against (usually `develop`). Run `cd ../warp-server && git status -sb && git --no-pager log -1` to confirm.
+
+## References
+
+- `scripts/sync_openapi.py` — the diff/apply tool
+- `references/sync-policy.md` — exclusion policy and how to extend it
+- `../warp-server/.agents/skills/update-open-api-spec/SKILL.md` — server-side workflow for editing the canonical spec
+- `../../../src/pages/api.astro` — how the docs site loads the YAML into Scalar