Documentation

docs/
├── docs/
│   ├── index.md
│   ├── usage/
│   │   ├── index.md
│   │   ├── commands/
│   │   │   ├── index.md
│   │   │   ├── install.md
│   │   │   ├── chat.md
│   │   │   ├── compile.md
│   │   │   └── run.md
│   │   ├── demo/
│   │   └── features/
│   ├── development/
│   │   ├── index.md
│   │   ├── build-and-test.md
│   │   ├── conventions-and-tips.md
│   │   ├── git-hooks.md
│   │   ├── continuous-integration.md
│   │   └── quickstart/
│   ├── code-base/
│   │   ├── index.md
│   │   ├── mekara/
│   │   │   ├── vcr-agent-recordings/
│   │   └── documentation/
│   │       ├── index.md
│   │       ├── conventions.md
│   │       ├── ui-customizations.md
│   │       └── components/
│   │           ├── index.md
│   │           └── claude-chat.md
│   ├── dependencies/
│   │   ├── index.md
│   │   └── claude-cli/
│   └── roadmap/
├── build/
├── sidebars.ts
├── docusaurus.config.ts
├── tsconfig.json
├── package.json
├── pnpm-lock.yaml
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
└── static/
    └── img/

The Docusaurus site that powers these docs lives entirely under the top-level docs/ directory. Within docs/, information is organized as such:

• docs/ stores the Markdown content you are reading. Organize new topics by folder so the autogenerated sidebar stays meaningful. Current top-level sections:

  • usage/ — End-user documentation: installation, CLI usage, and user-facing features.
  • development/ — Development workflows and processes for both human and AI agents.
  • code-base/ — Navigation guide to the codebase as a static entity: implementation details, gotchas, tests, and edge cases.
  • dependencies/ — Documentation for external packages mekara depends on, comprehensive enough for reimplementation without upstream docs.
  • roadmap/ — Design documents for planned features.

  See Standard Documentation: Documentation Layout for detailed guidance on what belongs in each section.

• docs/sidebars.ts, docs/docusaurus.config.ts, and docs/tsconfig.json contain site-level metadata, plugins, and TypeScript/MDX settings. Update them when you add new plugins, change navbar/footer items, or tweak MDX/React compilation.

• docs/src/ holds the React/TypeScript code for custom pages and components (for example, the home page hero). Update these files when you need custom UI beyond Markdown.

  • CSS is split into custom.css (always loaded) and fonts.css (conditionally loaded when private fonts are available).

• docs/static/ hosts assets that should be copied verbatim into the built site (favicons, downloadable files, etc.).

• docs/build/ is produced by pnpm build. It should be ignored in commits but is useful when you need to inspect the compiled files locally.

Make sure to capture any structure changes back in this doc so future agents know where to edit content.

Workflows

• cd docs && pnpm start to use the local dev server with hot reload.
• cd docs && pnpm build to produce a production build (this is done automatically by our Git pre-commit hooks)

Section Index

• Standard Mekara Documentation – Generic documentation standards that apply to all Mekara projects.
• Conventions – Project-specific documentation conventions (Docusaurus-specific conventions, mekara examples).
• UI Customizations – Custom styling and visual elements.
• Components – Custom React components for embedding rich content.
• Design Documents – Standard structure for roadmap and refactor plans.

Dependencies

• docusaurus for documentation website
• @testing-library/react and jest for component testing

Development Dependencies

• prettier for code formatting
• eslint for linting JavaScript/TypeScript
• typescript for type checking