mirror of https://github.com/rtk-ai/rtk.git synced 2026-09-19 07:33:17 +08:00

Files

T

Florian BRUNIAUX 6e55f8984c docs: address Adrien's review — structure, missing content, agents

Structure:
- Move docs/README.md → .github/docs-pipeline-contract.md (interface
  contract is not user-facing content)
- Rewrite docs/guide/index.md as a proper landing page with RTK intro,
  flow diagram, and navigation (replaces empty nav stub)
- Move configuration.md → getting-started/configuration.md (sidebar order 4,
  after supported-agents per Adrien's suggestion)

Missing content:
- Add docs/guide/analytics/discover.md: rtk discover (missed savings analysis)
  and rtk session (adoption tracking across sessions)
- Add uninstall instructions to installation.md (rtk init -g --uninstall,
  cargo uninstall, brew uninstall)
- Add global flags section to what-rtk-covers.md (-u/--ultra-compact,
  -v/--verbose)
- Add rtk smart command to what-rtk-covers.md Files section

Agents:
- Update supported-agents.md: 10 agents (was 9)
- Add OpenClaw (TypeScript plugin, before_tool_call)
- Add Mistral Vibe (planned, issue #800)
- Fix GitHub Copilot: VS Code = transparent rewrite via PreToolUse,
  Copilot CLI = deny-with-suggestion (upstream limitation)

Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com>

2026-04-06 11:16:24 +02:00

1.9 KiB

Raw Permalink Blame History

RTK Documentation — Interface Contract

This directory contains user-facing documentation for the RTK website. It feeds rtk-ai/rtk-website via the prepare-docs.mjs pipeline.

Scope: docs/guide/ is website content only. Technical and contributor documentation lives in the codebase (distributed, co-located pattern):

ARCHITECTURE.md — System design, ADRs, filtering strategies
CONTRIBUTING.md — Design philosophy, PR process, TOML vs Rust
SECURITY.md — Vulnerability policy
src/*/README.md — Per-module implementation docs
hooks/README.md — Hook system and agent integrations

Structure

docs/
  README.md      <- This file (interface contract — do not remove)
  guide/         -> User-facing documentation (website "Guide" tab)
    index.md
    getting-started/
      installation.md
      quick-start.md
      supported-agents.md
    what-rtk-covers.md
    analytics/
      gain.md
    configuration.md
    troubleshooting.md

Frontmatter (required on every .md)

Every markdown file under docs/guide/ must include:

---
title: string          # Page title (used in sidebar + search)
description: string    # One-line summary for search results and SEO
sidebar:
  order: number        # Position within the sidebar group (1 = first)
---

The prepare-docs.mjs pipeline validates this at build time and fails fast if frontmatter is missing or malformed.

Conventions

Filenames: kebab-case, .md only
Subdirectories: become sidebar groups in Starlight
Internal links: relative (./foo.md, ../configuration.md)
Diagrams: Mermaid in fenced code blocks
Code samples: always specify the language (rust, toml, bash)
Language: English only
No rtk <cmd> syntax: users never type rtk — hooks rewrite commands transparently. Only rtk gain, rtk init, rtk verify, and rtk proxy appear as user-typed commands.

1.9 KiB Raw Permalink Blame History

RTK Documentation — Interface Contract

Structure

Frontmatter (required on every .md)

Conventions

1.9 KiB

Raw Permalink Blame History