Merge branch 'main' into automation/sync-agent-api-spec

Author: rachaelrenk

.agents/skills/style_lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: style_lint
-description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, standardized screenshot widths, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix.
+description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, link quality, VideoEmbed titles, header case, missing frontmatter, image alt text, standardized screenshot widths, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix.
 ---
 
 # Style Lint
@@ -45,6 +45,9 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr
 - **UI elements after action verbs**: `click \`X\`` → should be `click **X**`
 - **Header case**: Title Case in H2/H3/H4 headers (should be sentence case, with exceptions for proper feature names)
 - **Missing frontmatter**: Pages without YAML `description` field
+- **Link anchor quality**: Empty anchors, raw URL anchors, and generic anchors like "here," "this page," "learn more," or "read more"
+- **Link context quality**: Redundant bold prefixes that repeat the link text, and named Oz web app page links missing articles like "the"
+- **VideoEmbed titles**: Missing `title` props and generic or numbered titles like "Video," "GitHub Actions video," or "Codebase Context video 1"
 - **Image alt text**: `<img>` or `<figure>` without alt text or with generic alt text ("screenshot", "image")
 - **Screenshot widths**: Likely UI/product screenshots must use `<figure style={{ maxWidth: "..." }}>` with a standard width (`300px`, `350px`, `375px`, or `563px`)
 - **Callout syntax**: Leftover GitBook `{% hint %}` tags that should be migrated to Starlight `:::note` / `:::caution` / `:::danger` asides
@@ -62,7 +65,7 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr
 
 When run with `--fix`:
 - **High-confidence fixes applied automatically**: Settings path format, UI element format, product name casing, external product name casing
-- **Low-confidence issues reported but not auto-fixed**: list format, header case (due to feature name exceptions), ambiguous terminology
+- **Low-confidence issues reported but not auto-fixed**: link quality, VideoEmbed title specificity, list format, header case (due to feature name exceptions), ambiguous terminology
 
 ## Relationship to validate_ui_refs
 

.agents/skills/style_lint/style_lint.py

@@ -119,6 +119,40 @@
     "use-cases",
 )
 
+GENERIC_LINK_ANCHORS = {
+    "click here",
+    "documentation",
+    "docs",
+    "here",
+    "learn more",
+    "link",
+    "more",
+    "page",
+    "read more",
+    "this article",
+    "this documentation",
+    "this guide",
+    "this link",
+    "this page",
+    "website",
+}
+
+GENERIC_VIDEO_TITLES = {
+    "demo",
+    "demo video",
+    "overview video",
+    "tutorial video",
+    "video",
+    "walkthrough video",
+}
+
+RAW_URL_ANCHOR = re.compile(
+    r"^(?:https?://|www\.|(?:[a-z0-9-]+\.)+(?:ai|app|co|com|dev|edu|gov|io|net|org)(?:/|$))",
+    re.IGNORECASE,
+)
+MARKDOWN_LINK = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
+VIDEO_EMBED_TITLE = re.compile(r"\btitle\s*=\s*([\"'])(.*?)\1", re.DOTALL)
+
 # Common bolded words that are NOT product terms (false positive suppression)
 COMMON_BOLD_WORDS = {
     # General emphasis words
@@ -194,7 +228,7 @@ def find_changed_md_files() -> List[Path]:
         for line in result.stdout.strip().split("\n"):
             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):
+                if not any(part in EXCLUDED_DIRS for part in p.parts) and not p.is_relative_to(CHANGELOG_DIR):
                     files.append(p)
         return sorted(files)
     except subprocess.CalledProcessError:
@@ -222,6 +256,104 @@ def check_frontmatter(content: str, filepath: str) -> List[Issue]:
     return issues
 
 
+def _strip_markdown_formatting(text: str) -> str:
+    """Remove lightweight Markdown/HTML formatting from link text."""
+    text = re.sub(r"`([^`]*)`", r"\1", text)
+    text = re.sub(r"\*\*([^*]*)\*\*", r"\1", text)
+    text = re.sub(r"__([^_]*)__", r"\1", text)
+    text = re.sub(r"\*([^*]*)\*", r"\1", text)
+    text = re.sub(r"_([^_]*)_", r"\1", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    return text
+
+
+def _normalize_link_text(text: str) -> str:
+    """Normalize link text for generic-anchor comparisons."""
+    text = _strip_markdown_formatting(text)
+    text = re.sub(r"\s+", " ", text).strip().lower()
+    return text.strip(" \t\n\r.,:;!?()[]{}\"'")
+
+
+def _meaningful_words(text: str) -> List[str]:
+    """Return lowercase words that carry semantic meaning for comparisons."""
+    stopwords = {"a", "an", "and", "for", "in", "of", "on", "the", "to", "with", "x"}
+    words = re.findall(r"[a-z0-9]+", text.lower())
+    return [word for word in words if len(word) > 2 and word not in stopwords]
+
+
+def check_link_quality(lines: List[str], filepath: str) -> List[Issue]:
+    """Check Markdown links for descriptive, contextual anchor text."""
+    issues = []
+    in_code_block = False
+    article_pattern = re.compile(
+        r"\b(go to|open|visit|navigate to|view)\s+\[((?:Runs|Integrations|Schedules|Environments|Secrets) page in the Oz web app)\]",
+        re.IGNORECASE,
+    )
+    redundant_prefix = re.compile(
+        r"^\s*[-*]\s+\*\*([^*]+)\*\*\s*[:—-]\s*\[([^\]]+)\]\([^)]+\)\.?\s*$"
+    )
+
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+
+        for m in MARKDOWN_LINK.finditer(line):
+            # Skip Markdown images.
+            if m.start() > 0 and line[m.start() - 1] == "!":
+                continue
+
+            anchor = m.group(1).strip()
+            normalized = _normalize_link_text(anchor)
+            if not normalized:
+                issues.append(Issue(
+                    filepath, i, "link-anchor",
+                    "Markdown link has empty anchor text; use descriptive link text that explains the destination",
+                    "error",
+                ))
+                continue
+
+            if RAW_URL_ANCHOR.match(normalized):
+                issues.append(Issue(
+                    filepath, i, "link-anchor",
+                    f"Raw URL used as link text: \"{anchor}\". Name the destination instead.",
+                    "warning",
+                ))
+            elif normalized in GENERIC_LINK_ANCHORS:
+                issues.append(Issue(
+                    filepath, i, "link-anchor",
+                    f"Generic link text: \"{anchor}\". Use descriptive anchor text that explains what users will find.",
+                    "warning",
+                ))
+
+        for m in article_pattern.finditer(line):
+            action = m.group(1)
+            page_name = m.group(2)
+            issues.append(Issue(
+                filepath, i, "link-context",
+                f"Add \"the\" before named destination page: \"{action} the [{page_name}]\"",
+                "warning",
+            ))
+
+        m = redundant_prefix.match(line)
+        if m:
+            prefix = _normalize_link_text(m.group(1))
+            anchor = _normalize_link_text(m.group(2))
+            prefix_words = _meaningful_words(prefix)
+            anchor_words = set(_meaningful_words(anchor))
+            if prefix_words and all(word in anchor_words for word in prefix_words):
+                issues.append(Issue(
+                    filepath, i, "link-context",
+                    f"Link text repeats the bold prefix \"{m.group(1)}\". Remove the prefix or add distinct context.",
+                    "warning",
+                ))
+
+    return issues
+
+
 def check_settings_paths(lines: List[str], filepath: str) -> List[Issue]:
     """Detect backtick-wrapped Settings paths that should be bold per-segment."""
     issues = []
@@ -438,6 +570,81 @@ def check_screenshot_widths(lines: List[str], filepath: str) -> List[Issue]:
     return issues
 
 
+def _iter_video_embed_tags(lines: List[str]) -> List[Tuple[int, str]]:
+    """Return (line_number, tag_text) for VideoEmbed components."""
+    tags: List[Tuple[int, str]] = []
+    in_code_block = False
+    collecting = False
+    start_line = 0
+    tag_parts: List[str] = []
+
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+
+        if not collecting and "<VideoEmbed" in line:
+            collecting = True
+            start_line = i
+            tag_parts = [line]
+            if ">" in line:
+                tags.append((start_line, "\n".join(tag_parts)))
+                collecting = False
+                tag_parts = []
+            continue
+
+        if collecting:
+            tag_parts.append(line)
+            if ">" in line:
+                tags.append((start_line, "\n".join(tag_parts)))
+                collecting = False
+                tag_parts = []
+
+    if collecting and tag_parts:
+        tags.append((start_line, "\n".join(tag_parts)))
+    return tags
+
+
+def _is_generic_video_title(title: str) -> bool:
+    """Return True when a VideoEmbed title is too generic for SEO/accessibility."""
+    normalized = re.sub(r"\s+", " ", title).strip().lower()
+    normalized = normalized.strip(" \t\n\r.,:;!?()[]{}\"'")
+    if normalized in GENERIC_VIDEO_TITLES:
+        return True
+    if re.search(r"\b(?:video|demo)\s+\d+\b", normalized):
+        return True
+    words = re.findall(r"[a-z0-9]+", normalized)
+    if normalized.endswith(" video") and len(words) <= 3:
+        return True
+    return False
+
+
+def check_video_embed_titles(lines: List[str], filepath: str) -> List[Issue]:
+    """Check VideoEmbed components for specific title props."""
+    issues = []
+    for line_number, tag in _iter_video_embed_tags(lines):
+        title_match = VIDEO_EMBED_TITLE.search(tag)
+        if not title_match or not title_match.group(2).strip():
+            issues.append(Issue(
+                filepath, line_number, "video-title",
+                "VideoEmbed missing title prop. Add a specific title that describes the integration, workflow, feature, or task shown.",
+                "error",
+            ))
+            continue
+
+        title = title_match.group(2).strip()
+        if _is_generic_video_title(title):
+            issues.append(Issue(
+                filepath, line_number, "video-title",
+                f"Generic VideoEmbed title: \"{title}\". Use a specific title that describes what the video shows.",
+                "warning",
+            ))
+    return issues
+
+
 def check_callout_syntax(lines: List[str], filepath: str) -> List[Issue]:
     """Check for malformed hint/callout syntax."""
     issues = []
@@ -664,9 +871,11 @@ def run_all_checks(filepath: Path) -> List[Issue]:
     issues.extend(check_frontmatter(content, str(filepath)))
     issues.extend(check_settings_paths(lines, str(filepath)))
     issues.extend(check_ui_element_backticks(lines, str(filepath)))
+    issues.extend(check_link_quality(lines, str(filepath)))
     issues.extend(check_header_case(lines, str(filepath)))
     issues.extend(check_image_alt_text(lines, str(filepath)))
     issues.extend(check_screenshot_widths(lines, str(filepath)))
+    issues.extend(check_video_embed_titles(lines, str(filepath)))
     issues.extend(check_callout_syntax(lines, str(filepath)))
     issues.extend(check_product_casing(lines, str(filepath)))
     issues.extend(check_oz_terms(lines, str(filepath)))

.agents/skills/triage-issue-local/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: triage-issue-local
+specializes: triage-issue
+description: Repo-specific triage guidance for the Warp docs repo. Only the categories declared overridable by the core triage-issue skill may be specialized here.
+---
+
+# Repo-specific triage guidance for `docs`
+
+This file is a companion to the core `triage-issue` skill. It does not
+redefine the triage output schema, safety rules, or follow-up-question
+contract. It only specializes the override categories the core skill
+marks as overridable.
+
+## Heuristics
+
+- `docs` is the public Warp documentation repository, built with Astro Starlight. Content lives in `src/content/docs/` as MDX files. Treat public issue reports as potentially incomplete.
+- Distinguish between **site bugs** (the docs platform is broken — search, navigation, rendering, styling, build errors) and **content issues** (documentation is incorrect, outdated, missing, unclear, has typos, or has formatting problems). Most issues will be content issues.
+- When the reporter provides a `docs.warp.dev` URL, map it to the source file: `docs.warp.dev/agent-platform/capabilities/skills` → `src/content/docs/agent-platform/capabilities/skills.mdx`.
+- When an issue claims documentation is wrong about a feature's behavior, verify against the source repos (`warp-internal` for client/Rust, `warp-server` for server/Go) before concluding the docs are incorrect. Docs are the primary source of truth for user-facing content, but source code is essential for validating accuracy when disputed.
+- Check the docs style guide (`AGENTS.md`) and terminology glossary (`.warp/references/terminology.md`) to validate that issue reports reference features by their correct names and that any proposed fixes would align with current terminology.
+- If the report is a support question (e.g., "How do I do X?") rather than an issue with the docs themselves, direct the reporter to the [Warp community Slack](https://go.warp.dev/join-preview) and the [docs site](https://docs.warp.dev).
+
+## Follow-up question limit
+
+Ask **at most 2 follow-up questions** per triage response. Each question must be high-value: it should meaningfully change the label assignment or reproduction confidence if answered. Do not ask questions whose answers can be inferred from the issue body, linked URLs, or screenshots.
+
+## Label taxonomy
+
+Use the following labels when triaging docs issues:
+
+**Priority labels** (always apply exactly one):
+- `priority/high` — Factually incorrect information, broken page, security-related content, or docs that cause users to take a wrong action
+- `priority/medium` — Outdated content, confusing instructions, incomplete coverage, or misleading screenshots
+- `priority/low` — Typos, minor formatting issues, small clarifications, nice-to-have improvements
+
+**Status labels:**
+- `triage` — Always apply on new issues. Signals the issue needs human review.
+- `ready-to-implement` — Reserved for human maintainers. Do not apply automatically; mention implementation readiness in the triage analysis instead.
+
+**Existing template labels** (applied automatically by issue templates — do not remove):
+- `bug` — Applied by the "Docs site bug" template
+- `improve or update documentation` — Applied by the "Docs content issue" template
+
+Do not invent new labels.
+
+## Information to check before asking follow-up questions
+
+Before asking the reporter for more information, check the issue body, comments, and attachments for:
+
+- The specific page URL(s) or topic area affected
+- What is incorrect, outdated, missing, or unclear (for content issues)
+- Browser and OS (for site bugs — search, rendering, navigation issues)
+- Screenshots or recordings showing the problem
+- Whether the reporter has already suggested a fix or correction
+- Whether the affected page exists in `src/content/docs/` and what it currently says
+
+## Recurring follow-up patterns
+
+- Content issue with no page URL: ask which page or topic is affected.
+- "Docs are wrong" with no source: ask for the expected behavior or a reference (release notes, CLI help output, changelog) that contradicts the current docs.
+- Site bug with no reproduction details: ask for browser, OS, and whether the issue persists in incognito/private browsing.
+
+## Content structure reference
+
+Documentation lives in `src/content/docs/` with these sections:
+- `terminal/` — Warp Terminal features (blocks, editor, sessions, appearance)
+- `agent-platform/` — Agent Platform (local agents, cloud agents, capabilities, integrations)
+- `code/` — Code editor, code review, git worktrees
+- `getting-started/` — Installation, setup, quickstart
+- `reference/` — CLI and API/SDK reference
+- `guides/` — Guides and tutorials
+- `knowledge-and-collaboration/` — Warp Drive, teams, Admin Panel
+- `support-and-community/` — Troubleshooting, billing, privacy
+- `enterprise/` — Enterprise features
+- `changelog/` — Release changelog
+
+The sidebar configuration is in `astro.config.mjs` at the repo root.