docs(kilo-docs): improve redirect guardrails

packages/kilo-docs/AGENTS.md

@@ -88,13 +88,25 @@ Use the Markdoc codicon tag format:
 
 1. Add a redirect entry to `previous-docs-redirects.js`
 2. Redirect format:
-   ```javascript
+    ```javascript
-   {
+    {
-     source: "/docs/old-path",
+      source: "/docs/old-path",
-     destination: "/docs/new-path",
+      destination: "/docs/new-path",
-     basePath: false,
+      basePath: false,
-     permanent: true,
+      permanent: true,
-   }
+    }
-   ```
+    ```
 3. Update the navigation file to remove or update the link
 4. Redirects are loaded in `next.config.js`
+
+### Redirect System
+
+`previous-docs-redirects.js` contains redirects for renamed/moved pages. Entries are organized in sections with comment headers for maintainability.
+
+**Tests:** Run `bun run test` to validate redirects:
+- Required fields (`source`, `destination`, `permanent: true`) are validated
+- No duplicate source paths
+- Source paths must start with `/docs/` (except `/auto-top-ups` for top-level redirects)
+- Section headers are required for organization
+
+**Adding redirects:** Place new redirects in the appropriate section or add a new section header. All redirects must use `basePath: false` to work correctly under the `/docs` base path.

packages/kilo-docs/__tests__/previous-docs-redirects.spec.ts

@@ -30,7 +30,7 @@ describe("previous-docs-redirects", () => {
 
   it("has valid redirect objects", () => {
     for (const redirect of entries) {
-      expect(redirect.source).toMatch(/^\//)
+      expect(redirect.source, `Source "${redirect.source}" must start with /docs/ (or /auto-top-ups for top-level redirects)`).toMatch(/^\/(?:docs\/|auto-top-ups$)/)
       expect(redirect.destination).toMatch(/^(?:\/|https:\/\/)/)
       expect(redirect.basePath).toBe(false)
       expect(redirect.permanent).toBe(true)
@@ -139,4 +139,11 @@ describe("previous-docs-redirects", () => {
       expect(redirect.destination).toMatch(/\.md(?:#.*)?$/)
     }
   })
+
+  it("uses section headers for organization", () => {
+    const redirectFile = path.join(pages, "..", "previous-docs-redirects.js")
+    const file = fs.readFileSync(redirectFile, "utf8")
+    const sections = file.match(/\/\/\s*=+\s*\n\s*\/\/\s*[A-Z][A-Z\s]+\n/g)
+    expect(sections && sections.length >= 1, "Should have at least one section header for organization").toBeTruthy()
+  })
 })