docs(kilo-docs): clarify contributor architecture docs

packages/kilo-docs/__tests__/heading.test.ts

@@ -0,0 +1,17 @@
+import { Tag } from "@markdoc/markdoc"
+import { describe, expect, it } from "vitest"
+import { heading } from "../markdoc/nodes/heading.markdoc"
+
+describe("heading", () => {
+  it("includes inline code text in generated ids", () => {
+    const tag = heading.transform(
+      {
+        transformAttributes: () => ({}),
+        transformChildren: () => [new Tag("code", {}, ["kilo-auto/frontier"])],
+      },
+      {},
+    )
+
+    expect(tag.attributes.id).toBe("kilo-autofrontier")
+  })
+})

packages/kilo-docs/lib/nav/contributing.ts

@@ -1,10 +1,10 @@
-import { NavSection } from "../types"
+import type { NavSection } from "../types"
 
 export const ContributingNav: NavSection[] = [
   {
     title: "Getting Started",
     links: [
-      { href: "/contributing", children: "Contributing Overview" },
+      { href: "/contributing", children: "Overview" },
       {
         href: "/contributing/development-environment",
         children: "Development Environment",
@@ -20,61 +20,69 @@ export const ContributingNav: NavSection[] = [
     links: [
       {
         href: "/contributing/architecture",
-        children: "Architecture Overview",
-      },
-      {
-        href: "/contributing/architecture/features",
-        children: "Features",
-        subLinks: [
-          {
-            href: "/contributing/architecture/agent-observability",
-            children: "Agent Observability",
-          },
-          {
-            href: "/contributing/architecture/auto-model-tiers",
-            children: "Auto Model Tiers",
-          },
-          {
-            href: "/contributing/architecture/benchmarking",
-            children: "Benchmarking",
-          },
-          {
-            href: "/contributing/architecture/config-schema",
-            children: "CLI Config Schema",
-          },
-          {
-            href: "/contributing/architecture/enterprise-mcp-controls",
-            children: "Enterprise MCP Controls",
-          },
-          {
-            href: "/contributing/architecture/mcp-oauth-authorization",
-            children: "MCP OAuth Authorization",
-          },
-          {
-            href: "/contributing/architecture/onboarding-improvements",
-            children: "Onboarding Improvements",
-          },
-          {
-            href: "/contributing/architecture/organization-modes-library",
-            children: "Organization Modes Library",
-          },
-          {
-            href: "/deploy-secure/security-reviews",
-            children: "Agentic Security Reviews",
-          },
-          {
-            href: "/contributing/architecture/track-repo-url",
-            children: "Track Repo URL",
-          },
-          {
-            href: "/contributing/architecture/voice-transcription",
-            children: "Voice Transcription",
-          },
-          {
-            href: "/contributing/architecture/per-message-feedback",
-            children: "Per-Message Feedback",
-          },
-        ],
+        children: "Overview",
+      },
+      {
+        href: "/contributing/architecture/cli-runtime",
+        children: "CLI Runtime",
+      },
+      {
+        href: "/contributing/architecture/vscode-extension",
+        children: "VS Code Extension",
+      },
+      {
+        href: "/contributing/architecture/jetbrains-plugin",
+        children: "JetBrains Plugin",
+      },
+      {
+        href: "/contributing/architecture/cloud-platform",
+        children: "Cloud Platform",
+      },
+      {
+        href: "/contributing/architecture/automation-services",
+        children: "Automation Services",
+      },
+      {
+        href: "/contributing/architecture/cloud-security",
+        children: "Cloud Security",
+      },
+    ],
+  },
+  {
+    title: "Development",
+    links: [
+      {
+        href: "/contributing/architecture/development-patterns",
+        children: "Development Patterns",
+      },
+      {
+        href: "/contributing/architecture/config-schema",
+        children: "CLI Config Schema",
+      },
+    ],
+  },
+  {
+    title: "Feature Proposals",
+    links: [
+      {
+        href: "/contributing/features",
+        children: "Overview",
+      },
+      {
+        href: "/contributing/features/enterprise-mcp-controls",
+        children: "Enterprise MCP Controls",
+      },
+      {
+        href: "/contributing/features/onboarding-improvements",
+        children: "Onboarding Improvements",
+      },
+      {
+        href: "/contributing/features/agent-observability",
+        children: "Agent Observability",
+      },
+      {
+        href: "/contributing/features/benchmarking",
+        children: "Benchmarking",
       },
     ],
   },

packages/kilo-docs/markdoc/nodes/heading.markdoc.ts

@@ -2,14 +2,20 @@ import { Tag } from "@markdoc/markdoc"
 
 import { Heading } from "../../components"
 
+function text(child) {
+  if (typeof child === "string") return child
+  if (Tag.isTag(child)) return child.children.map(text).join(" ")
+  return ""
+}
+
 function generateID(children, attributes) {
   if (attributes.id && typeof attributes.id === "string") {
     return attributes.id
   }
   return children
-    .filter((child) => typeof child === "string")
+    .map(text)
     .join(" ")
-    .replace(/[?]/g, "")
+    .replace(/[?/]/g, "")
     .replace(/\s+/g, "-")
     .toLowerCase()
 }

packages/kilo-docs/markdoc/tags/index.ts

@@ -10,3 +10,4 @@ export * from "./video.markdoc"
 export * from "./youtube.markdoc"
 export * from "./flow-diagram.markdoc"
 export * from "./browser-frame.markdoc"
+export * from "./linebreak.markdoc"

packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts

@@ -0,0 +1,4 @@
+export const linebreak = {
+  render: "br",
+  selfClosing: true,
+}

packages/kilo-docs/package.json

@@ -5,8 +5,10 @@
   "scripts": {
     "dev": "next dev --webpack --port 3002",
     "build": "next build --webpack",
+    "lint": "bun run --cwd ../.. lint packages/kilo-docs",
     "start": "next start",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@docsearch/css": "^4",

packages/kilo-docs/pages/code-with-ai/agents/auto-model.md

@@ -1,11 +1,11 @@
 ---
 title: "Auto Model"
-description: "Smart model routing that automatically selects the optimal AI model based on your current mode"
+description: "Smart model routing that selects an AI model for each Auto Model tier"
 ---
 
 # Auto Model
 
-Auto Model is a smart model routing system that automatically selects the optimal AI model based on the Kilo Code mode you're using. It comes in multiple tiers so you can balance cost and capability to fit your needs.
+Auto Model is a smart routing system that selects an underlying model for each request. Each tier uses its own routing strategy so you can balance cost and capability to fit your needs.
 
 | Tier | Best For | Pricing |
 |---|---|---|