feat: add AGENTS.md files for various rules and guidelines; enhance search bar functionality for release notes (#339)

Author: hannesrudolph

.roo/rules-architect/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+- Theme components swizzled from Docusaurus core; modifying requires understanding [src/theme/](src/theme/) override hierarchy.
+- Sitemap uses custom plugin ([docusaurus.config.ts](docusaurus.config.ts:94-107)) filtering "/page/" URLs; preset sitemap disabled. Don't re-enable preset.
+- Redirects required when moving docs ([docusaurus.config.ts](docusaurus.config.ts:109-271)); onBrokenLinks won't fail builds but creates poor UX.
+- Constants centralized in [src/constants.ts](src/constants.ts) for all external URLs. Never hardcode URLs in config or components.
+- PostHog analytics conditionally loaded based on env var ([docusaurus.config.ts](docusaurus.config.ts:84-93)); architectural decision for privacy/GDPR.
+- Search uses local plugin (@easyops-cn/docusaurus-search-local) with docsRouteBasePath "/" - maintain consistency.
+- No blog feature (disabled in preset); this is pure documentation site, not a content platform.

.roo/rules-ask/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+- Docusaurus docs, not source code. This is documentation for the Roo Code VS Code extension at docs.roocode.com.
+- Legacy [Rakefile](Rakefile) is from old Jekyll site. Ignore it; current build uses Docusaurus/npm scripts.
+- Tutorial videos defined in [docs/tutorial-videos.json](docs/tutorial-videos.json), dynamically loaded in [sidebars.ts](sidebars.ts:37-42). Titles truncated to 40 chars.
+- Release notes have thanking exclusions: don't thank daniel-lxs, cte, hannesrudolph, jr, roomote, app/roomote, dleffel, mrubens per [.roorules](.roorules:14).
+- Many docs moved; check redirects in [docusaurus.config.ts](docusaurus.config.ts:109-271) when referencing old paths.
+- Context7 MCP configured in [.roo/mcp.json](.roo/mcp.json) with library ID "/facebook/docusaurus" for structural research.
+- Sidebar structure in [sidebars.ts](sidebars.ts) has nested categories; update-notes organized by major.minor versions.

.roo/rules-code/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+- Linting targets only /src; docs are excluded. Use "npm run lint:unused" to enforce removal of unused imports. See [package.json](package.json).
+- Type checking uses tsc only (no emit); [tsconfig.json](tsconfig.json) is editor-focused. Run "npm run typecheck" locally; CI does not typecheck.
+- Use Docusaurus @site alias for cross-root imports from theme/MDX; example at [src/theme/MDXComponents.ts](src/theme/MDXComponents.ts:2).
+- Centralize external URLs in [src/constants.ts](src/constants.ts); consumed by [docusaurus.config.ts](docusaurus.config.ts:21) for navbar/footer.
+- When moving docs, add redirects in [docusaurus.config.ts](docusaurus.config.ts:109); onBrokenLinks is warn ([docusaurus.config.ts](docusaurus.config.ts:40)) so missing redirects won’t fail CI.
+- Internal doc links must be absolute and extensionless per [.roorules](.roorules) (e.g., /basic-usage/how-tools-work).
+- Images in docs must use HTML tags: <img src="/img/...png" alt="..." width="600" /> (Markdown image syntax is disallowed).
+- Builds preload dotenv; PostHog plugin loads only when POSTHOG_API_KEY is set. Use [.env.example](.env.example). See [docusaurus.config.ts](docusaurus.config.ts:83) and [package.json](package.json:7).
+- Use Node 20 locally to match CI ([.github/workflows/docusaurus-build.yml](.github/workflows/docusaurus-build.yml:23)); package engines allow >=18.
+- “Tutorial Videos” sidebar is driven by [docs/tutorial-videos.json](docs/tutorial-videos.json); titles truncated to 40 chars in [sidebars.ts](sidebars.ts:5).

.roo/rules-debug/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+- CI only builds, doesn't lint/typecheck ([.github/workflows/docusaurus-build.yml](.github/workflows/docusaurus-build.yml:29)). Run "npm run lint" and "npm run typecheck" locally before pushing.
+- PostHog analytics silently skips if POSTHOG_API_KEY missing. Check [.env](.env) exists with key from [.env.example](.env.example).
+- No test framework configured. Scripts exist in package.json but no test files or jest/vitest config present.
+- Docusaurus dev server at localhost:3000. Hot reload may fail for theme swizzled components; restart if changes don't appear.
+- onBrokenLinks set to "warn" ([docusaurus.config.ts](docusaurus.config.ts:40)) - broken links won't fail build but check console warnings.
+- Node version mismatch (engines >=18, CI uses 20) can cause subtle differences. Use Node 20 locally.

AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+Non-obvious, project-specific rules:
+
+- Start/build preload dotenv; analytics plugin is enabled only when POSTHOG_API_KEY is set. Use .env based on [.env.example](.env.example). CI injects it in [.github/workflows/docusaurus-build.yml](.github/workflows/docusaurus-build.yml). See [package.json](package.json) and [docusaurus.config.ts](docusaurus.config.ts).
+- Use Node 20 locally to match CI; engines allow >=18 but CI runs 20.
+- Linting targets only /src; docs content is not linted. Use "npm run lint:unused" to enforce unused import removal. Type checking uses "tsc" only (no emit); [tsconfig.json](tsconfig.json) is editor-focused.
+- When moving/renaming docs, you must add an explicit redirect in [docusaurus.config.ts](docusaurus.config.ts) under plugin-client-redirects. This is required by [.roorules](.roorules).
+- Internal doc links must be absolute and extensionless per [.roorules](.roorules) (example: /basic-usage/how-tools-work). Do not include ".md".
+- Images in docs must use HTML tags per [.roorules](.roorules): <img src="/img/...png" alt="..." width="600" />.
+- Sitemap: preset sitemap is disabled; a custom plugin is configured in [docusaurus.config.ts](docusaurus.config.ts) to filter URLs containing "/page/". Do not re-enable the preset sitemap.
+- Local search plugin is configured with docsRouteBasePath "/". Keep routeBasePath "/" consistent when adding content or links.
+- "Tutorial Videos" sidebar is generated from [docs/tutorial-videos.json](docs/tutorial-videos.json); titles are truncated to 40 chars in [sidebars.ts](sidebars.ts). Modify the JSON to add/remove videos.
+- Navigation/footer links are centralized in [src/constants.ts](src/constants.ts) and consumed by [docusaurus.config.ts](docusaurus.config.ts). Update constants rather than hardcoding URLs.
+- Legacy [Rakefile](Rakefile) is unrelated (Jekyll). Do not use it; all builds run through Docusaurus scripts.
+- For structural/formatting research, use Context7 MCP (ID "/facebook/docusaurus") via [.roo/mcp.json](.roo/mcp.json); see [.roorules](.roorules).
+- CI only builds (no lint/typecheck). Run lint and typecheck locally to catch issues CI won't.

docusaurus.config.ts

@@ -76,6 +76,16 @@ const config: Config = {
         highlightSearchTermsOnTargetPage: true,
         explicitSearchResultPath: true,
         docsRouteBasePath: "/",
+        searchContextByPaths: [
+          { label: "Getting Started", path: "getting-started" },
+          { label: "Basic Usage", path: "basic-usage" },
+          { label: "Features", path: "features" },
+          { label: "Advanced Usage", path: "advanced-usage" },
+          { label: "Providers", path: "providers" },
+          { label: "Roo Code Cloud", path: "roo-code-cloud" },
+          { label: "Release Notes", path: "update-notes" }
+        ],
+        useAllContextsWithNoSearchContext: true,
       },
     ],
   ],

src/theme/SearchBar/index.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useLocation} from '@docusaurus/router';
+import OriginalSearchBar from '@theme-original/SearchBar';
+
+type Props = React.ComponentProps<typeof OriginalSearchBar>;
+
+export default function SearchBarWrapper(props: Props) {
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+  const location = useLocation();
+
+  // When on /update-notes/*, show a clear "scope indicator" and a shortcut to search the whole docs
+  const inReleaseNotes =
+    location.pathname === `${baseUrl}update-notes` ||
+    location.pathname.startsWith(`${baseUrl}update-notes/`);
+
+  const searchEverywhereHref = `${baseUrl}search/`;
+
+  return (
+    <div style={{display: 'flex', alignItems: 'center', gap: '0.5rem'}}>
+      <OriginalSearchBar {...props} />
+      {inReleaseNotes && (
+        <span
+          className="badge badge--secondary"
+          title="Search currently scoped to Release Notes on this page"
+        >
+          Release Notes
+        </span>
+      )}
+      {inReleaseNotes && (
+        <Link
+          className="button button--link"
+          href={searchEverywhereHref}
+          title="Open full-site search (all docs)"
+          style={{marginLeft: '0.25rem'}}
+        >
+          Search everywhere
+        </Link>
+      )}
+    </div>
+  );
+}