How these docs work

This site is organized by repository. Each repository gets a section with the same shape, work that spans repositories has a section of its own, and every kind of page has a template. The sidebar is built from the files on disk, so adding documentation means adding files. There is no config to edit.

Layout on disk

docs/
├── index.md                     Home
├── guide/                       Getting started, plus this page
├── repos/
│   ├── index.md                 Repository list
│   └── <repo>/                  One folder per repository
│       ├── index.md             Overview (frontmatter drives the switcher)
│       ├── architecture.md
│       ├── modules/             index.md + one page per module
│       ├── components/          index.md + one page per component
│       ├── functions/           index.md + one page per function
│       ├── apis/                index.md + one page per API
│       ├── configuration.md
│       ├── dependencies.md
│       └── contributing.md
├── cross-repo/                  Architecture, dependencies, communication,
│                                data flow, shared components, E2E flows
├── templates/                   The page templates (also used by the generators)
│
├── website/  ui-features/  execution/  oa-integrity/  backend/
├── desktop/  tools/  docy/      Long-form guides (original URLs), shown in
│                                each repository's sidebar under "Guides"
└── reference/  contributing/    Organization-wide reference and process

Adding documentation

To add…	Do this
A module, component, function or API page	npm run new:page -- <repo> <module|component|function|api> <page-slug> "<Title>"
A whole repository	npm run new:repo -- <repo-slug> "<Name>" "<Description>" --icon <icon> --order <n> (see Adding a Repository)
A new kind of section in one repository	Create a folder in docs/repos/<repo>/ (for example guides/) with an index.md. It appears in that repository's sidebar.
A cross-repository page	Add it to docs/cross-repo/ and link it from the Cross-repository list in docs/.vitepress/config.mjs

Pages can also be created by hand. Copy the block under Template from the matching template page.

Conventions

Naming

• Folders and files are lowercase kebab-case: run-code.md, use-auth.md.
• Repository folders use the repository name in kebab-case (ediky_tools → ediky-tools). The display name lives in the overview's frontmatter title:.
• Page titles go in frontmatter title:. The sidebar and breadcrumbs use it, falling back to the page's first # heading.

Frontmatter

Key	Used on	Effect
title	every page	Sidebar label, breadcrumb, browser tab
description	every page	Search and link previews. On a repository overview, the switcher subtitle
status: draft	skeleton pages	Shows a Draft badge beside the breadcrumbs. Delete it once the page is written
order	section pages	Position within its sidebar section (lower first, then alphabetical)
icon	repository overview	Icon in the switcher, sidebar and home page (names are in docs/.vitepress/icons.mjs)
github	repository overview	Shown in the overview's At a glance table

Content

• One concept per page. Split long pages rather than growing them.
• Keep template headings. If a heading doesn't apply, write Not applicable and say why.
• TODO marks unfinished content. Search for it to find the gaps.
• Diagrams go in fenced mermaid blocks, with zoom, pan and fullscreen built in.
• Link, don't copy. When another page already explains something, link to it.

How the site is built

• VitePress, with a thin custom theme in docs/.vitepress/theme/.
• Sidebar: docs/.vitepress/config.mjs builds the general sidebar. docs/.vitepress/lib/docs-tree.mjs builds each repository's sidebar from its folder.
• Search: local full-text search (Ctrl K / ⌘ K) over every page.
• Ask AI: the assistant in the bottom-right corner answers from these pages. Its index is rebuilt on every npm run dev / npm run build.