docs(kilo-docs): clarify contributor architecture docs

[jeanduplessis]

Summary

Clarify contributor architecture documentation around stable local and hosted boundaries so developers can form a consistent mental model before changing implementation code.

Why this change is needed

Architecture docs had grown into overlapping walkthroughs, feature proposals, and service inventories. Readers had to reconstruct local runtime ownership, Cloud Agent boundaries, automation flows, cloud trust boundaries, and config contracts across several disconnected pages.

How this is addressed

• Reframe contributor architecture docs around one mental model: local runtime, Kilo Cloud shared services, hosted execution boundaries, automation lifecycle, and cloud security controls.
• Separate feature proposals from current-state architecture and redirect removed walkthrough routes to durable anchors.
• Document CLI runtime, VS Code extension, JetBrains plugin, cloud platform, automation services, cloud security, development patterns, and CLI config schema as complementary pages with explicit ownership.
• Replace dense text trees and legacy image assets with Mermaid diagrams for App Builder, Security Agent, chat delivery, KiloClaw, and config-schema flows.
• Add repository-relative source maps, related-page links, a Markdoc line-break helper for stacked table paths, and focused heading regression coverage.

Human Verification

• Ran bun run test in packages/kilo-docs: 3 files, 9 tests passed.
• Ran bun run build in packages/kilo-docs: 236 static pages generated.
• Browser-checked built docs navigation, architecture anchors, Mermaid SVG rendering, removed KiloClaw image absence, and permanent redirect targets.

Manual browser verification

• Confirmed Cloud Security navigation label renders.
• Confirmed removed architecture walkthrough routes return 308 redirects to stable anchors.
• Confirmed #chat-events-and-notifications, #bundled-resources, #privacy-logging-and-retention, and Security Agent anchors resolve.
• Confirmed Cloud Platform and Cloud Security Mermaid diagrams render.

Reviewer Notes

Human Reviewer Flags

• Public architecture pages now focus on durable boundaries. Source code remains reference for feature-level plumbing.
• Cloud Agent is documented as one active capability; services/cloud-agent-next/ remains current session-runtime source path without legacy Cloud Agent references.
• CLI runtime config loading and cloud-served JSON Schema validation are intentionally documented as separate cross-repository contracts.
• Feature proposals now live outside current-state Architecture navigation.

Code Reviewer Agent

Code Reviewer Notes

• Removed walkthrough routes retain permanent redirects to stable architecture anchors.
• Markdoc {% linebreak /%} renders stacked source paths in dense architecture tables.
• Comma-bearing architecture headings were renamed locally so expected anchors resolve without changing global slug behavior for unrelated docs.
• Legacy KiloClaw diagram PNG and orphaned walkthrough images were removed after Mermaid replacement.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs (docs-staging)	Ready	Preview, Comment	Jun 3, 2026 6:22pm

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Remains (Previous) | Recommendation: Minor, non-blocking

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

Changes since last review

Change	Status
packages/kilo-docs/PLAN.md (previous WARNING)	RESOLVED — file removed from branch
packages/kilo-docs/mappingplan.md (previous WARNING)	STILL EXISTS — 188-line internal planning doc present on branch but not modified in this PR. Carry forward.
heading.markdoc.ts text() extra-space note (previous SUGGESTION)	Unchanged — logic unmodified, observation still applies

WARNING (carried forward)

File	Issue
packages/kilo-docs/mappingplan.md	Internal mapping plan still committed to repo. Not surfaced in site nav but publicly visible in source. Consider whether this should be removed or .gitignored after the restructure work is complete.

SUGGESTION (carried forward)

File	Issue
packages/kilo-docs/markdoc/nodes/heading.markdoc.ts	The text() helper at line 7 joins Tag children with " ". If a Tag child itself wraps multiple strings (e.g. "Prefix " + codetype + " suffix"), the recursive join inserts an extra space between adjacent segments. The outer \s+ → - collapse handles it correctly in practice, but a comment or test case covering that shape would make intent explicit for future maintainers.

New content verified (this revision)

• All new architecture pages (cli-runtime.md, vscode-extension.md, jetbrains-plugin.md, cloud-platform.md, automation-services.md, cloud-security.md, development-patterns.md) have correct frontmatter, single h1, and sequential heading hierarchy.
• All redirect destinations verified against actual headings in new pages:
  • cli-runtime#remote-mcp-oauth ✓
  • cli-runtime#config-precedence ✓
  • cloud-platform#kilo-gateway ✓
  • cloud-platform#security-agent ✓
  • vscode-extension#bundled-resources ✓
  • cloud-security#privacy-logging-and-retention ✓
  • cloud-security#security-agent-sync-and-cleanup ✓
  • contributing/features/* redirects ✓
• New linebreak Markdoc tag is correctly defined and exported.
• package.json lint and typecheck scripts are clean additions.
• Nav restructuring in contributing.ts references all correct href paths.
• mappingplan.md is NOT in the current PR diff — it predates this PR. Only the file's continued presence on the branch is flagged (carried forward).

Files Reviewed

• packages/kilo-docs/__tests__/heading.test.ts
• packages/kilo-docs/lib/nav/contributing.ts
• packages/kilo-docs/markdoc/nodes/heading.markdoc.ts
• packages/kilo-docs/markdoc/tags/index.ts
• packages/kilo-docs/markdoc/tags/linebreak.markdoc.ts
• packages/kilo-docs/package.json
• packages/kilo-docs/pages/code-with-ai/agents/auto-model.md
• packages/kilo-docs/pages/contributing/architecture/cli-runtime.md (new)
• packages/kilo-docs/pages/contributing/architecture/vscode-extension.md (new)
• packages/kilo-docs/pages/contributing/architecture/jetbrains-plugin.md (new)
• packages/kilo-docs/pages/contributing/architecture/cloud-platform.md (new)
• packages/kilo-docs/pages/contributing/architecture/automation-services.md (new)
• packages/kilo-docs/pages/contributing/architecture/cloud-security.md (new)
• packages/kilo-docs/pages/contributing/architecture/development-patterns.md (new)
• packages/kilo-docs/pages/contributing/architecture/config-schema.md (updated)
• packages/kilo-docs/pages/contributing/architecture/index.md (updated)
• packages/kilo-docs/pages/contributing/features/index.md (new)
• packages/kilo-docs/pages/contributing/features/enterprise-mcp-controls.md (new)
• packages/kilo-docs/pages/contributing/features/onboarding-improvements.md (new)
• packages/kilo-docs/pages/contributing/features/agent-observability.md (new)
• packages/kilo-docs/pages/contributing/features/benchmarking.md (new)
• packages/kilo-docs/pages/contributing/features/template.md (new)
• packages/kilo-docs/pages/contributing/index.md
• packages/kilo-docs/pages/gateway/models-and-providers.md
• packages/kilo-docs/previous-docs-redirects.js
• Deleted pages (12) and deleted images (5) verified

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-sonnet-4.6 · 1,920,074 tokens}

_{Review guidance: REVIEW.md from base branch main}