Documentation Reorganization

Introduction

The mekara documentation needed restructuring to better separate standards (timeless best practices) from wiki content (how-to guides). This reorganization establishes a clear information architecture with a unified Standards section and separate Wiki tab, making it easier for both humans and AI agents to find relevant information.

Objectives

Reorganize the documentation to:

Move mekara standards to a unified standards/ folder (sidebar position 3, after philosophy)
Move project commands to wiki/project/ and symlink them from .claude/commands/project/
Create a separate "Wiki" tab at the top level of the Docusaurus site
Standardize design document terminology and structure across all planning workflows

Architecture

Before:

docs/docs/
├── code-base/
│   ├── mekara/standard-mekara-project.md
│   └── documentation/
│       ├── standard-mekara-docs.md
│       └── planning-documents.md
├── usage/standard-mekara-workflow.md
└── roadmap/

.claude/commands/           # Directory with .md files
.mekara/scripts/            # Directory with .py files

After:

docs/
├── docs/
│   ├── standards/          # NEW: Unified standards section
│   │   ├── project.md
│   │   ├── documentation.md
│   │   ├── workflow.md
│   │   └── design-documents.md
│   └── roadmap/
└── wiki/                   # NEW: Separate Wiki plugin
    ├── ai-tooling/
    ├── project/
    └── target-platform/

.mekara/scripts/
├── nl/                     # Natural language scripts (source of truth)
│   ├── plan-design-doc.md  # Renamed from plan-roadmap.md
│   └── project/
└── compiled/               # Compiled scripts (source of truth)

.claude/commands/           # Symlink → .mekara/scripts/nl/

Design Details

File Organization Principles

Standards (docs/docs/standards/) contain timeless best practices and structural requirements
Wiki (docs/wiki/) contains practical how-to guides organized by category
Roadmap (docs/docs/roadmap/) contains design documents for planned features

Symlink Strategy

.claude/commands/ is a symlink to .mekara/scripts/nl/ for backward compatibility
Wiki content is copied (not symlinked) from .mekara/scripts/nl/ - the mekara scripts are the source of truth

Invariants

All file moves must preserve git history via git mv
Build must pass after each phase
All cross-references must be updated when files move

Implementation Plan

Phase 1: Docusaurus Configuration ✅

Goal: Set up Wiki as a separate Docusaurus plugin with its own sidebar

Tasks:

Create docs/sidebarsWiki.ts for wiki sidebar configuration
Update docs/docusaurus.config.ts to add wiki plugin and navbar item
Create initial docs/wiki/index.md with user's updated content
Verify configuration works with test build

Phase 2: Standards Reorganization ✅

Goal: Move all standards to a unified docs/docs/standards/ folder at sidebar position 3

Tasks:

Create docs/docs/standards/ folder structure
Create docs/docs/standards/index.md with overview
Move files with git mv (preserves history):
- code-base/mekara/standard-mekara-project.md → standards/project.md
- code-base/documentation/standard-mekara-docs.md → standards/documentation.md
- usage/standard-mekara-workflow.md → standards/workflow.md
Update internal cross-references within moved files
Update sidebar positions to integers:
- Philosophy: sidebar_position: 2
- Standards: sidebar_position: 3
- Usage: sidebar_position: 4
- Development: sidebar_position: 5
- Code Base: sidebar_position: 6
Update all external references across documentation:
- docs/docs/index.md
- docs/docs/philosophy.md
- docs/docs/usage/index.md
- docs/docs/development/quickstart/for-humans.md
- docs/docs/code-base/mekara/index.md
- docs/docs/code-base/documentation/index.md
Fix cross-plugin link in wiki/index.md
Verify build succeeds with no broken links

Phase 3: Complete Standards Section ✅

Goal: Add design documents standard and clean up sidebar labels

Tasks:

Move code-base/documentation/design-documents.md to standards/ with git mv
Update design-documents.md title to "Standard Mekara Design Documents"
Update standards/index.md:
- Change "three core standards" to "four core standards"
- Add link: - [Design Documents](./design-documents.md) – Standard structure for roadmap and refactor plans
Update all references to design-documents.md path:
- .claude/commands/plan-design-doc.md
- .claude/commands/plan-refactor.md
- docs/docs/code-base/documentation/index.md
- Any other files found via grep
Run bundle scripts to sync changes to src/mekara/bundled/scripts/
Remove "Standard Mekara" prefix from sidebar labels (keep in page titles):
- project.md: Add sidebar_label: "Project" (title stays "Standard Mekara Project")
- documentation.md: Add sidebar_label: "Documentation" (title stays "Standard Mekara Documentation")
- workflow.md: Add sidebar_label: "Workflow" (title stays "Standard Mekara Workflow")
- design-documents.md: Add sidebar_label: "Design Documents" (title becomes "Standard Mekara Design Documents")
Verify build succeeds with no broken links

Phase 4: Restructure Scripts Directory ✅

Goal: Reorganize .mekara/scripts/ and create symlink from .claude/commands/

Current structure:

.claude/commands/           # Directory with .md files
.mekara/scripts/            # Directory with .py files

Target structure:

.mekara/scripts/
├── nl/                     # Natural language scripts (source of truth)
│   ├── *.md               # Non-project commands
│   └── project/           # Project commands
│       └── *.md
└── compiled/              # Compiled scripts (source of truth)
    ├── *.py               # Non-project compiled scripts
    └── project/           # Project compiled scripts
        └── *.py

.claude/commands/          # Symlink → .mekara/scripts/nl/

Tasks:

Phase 5: Create Wiki as Documentation Copy ✅

Goal: Create wiki structure with "How To's" organized by category

Note: These are documentation copies, not symlinks. The source of truth remains in .mekara/scripts/nl/.

Tasks:

Phase 6: Update Standard Mekara Workflow ✅

Goal: Simplify workflow documentation to reference only /project:new

File: docs/docs/standards/workflow.md

Tasks:

Remove detailed references to individual setup scripts (setup-docs, setup-github-pages, etc.)
Keep only /project:new as the main entry point
Update "Get In" section to focus on the orchestrated command

Phase 7: Standardize Design Document Terminology ✅

Goal: Update planning documents to use "design documents" terminology and restructure to match new standard

Tasks:

Phase 8: Update Standard Mekara Project Documentation and Scripts ✅

Goal: Update documentation and scripts to reflect new directory structure, and implement bidirectional sync

Content Sync Principle: Content between .mekara/scripts/nl/project/*.md and docs/wiki/project/*.md should be copied verbatim, except that docs/wiki/project/*.md files have Docusaurus frontmatter prepended (sidebar_label, sidebar_position). The body content must be identical.

Tasks:

Phase 9: Verification ✅

Goal: Verify all changes work correctly

Tasks:

Run pnpm run build - verify no broken links
Start dev server with pnpm start - verify navigation works
Check Standards appears at position 3 in sidebar
Verify Wiki tab shows separate sidebar
Verify wiki sidebar only contains Wiki intro and Project commands
Test symlink: cat .claude/commands/project/new.md should work
Run git status - verify clean working tree
Verify all file moves tracked with git mv (should show as renames)

Notes

All git mv operations preserve file history
Wiki and Docs are separate Docusaurus plugins with independent sidebars
.claude/commands/ symlink maintains backward compatibility
Pre-commit hook ensures bundled scripts stay in sync with sources

Introduction​

Objectives​

Architecture​

Design Details​

File Organization Principles​

Symlink Strategy​

Invariants​

Implementation Plan​

Phase 1: Docusaurus Configuration ✅​

Phase 2: Standards Reorganization ✅​

Phase 3: Complete Standards Section ✅​

Phase 4: Restructure Scripts Directory ✅​

Phase 5: Create Wiki as Documentation Copy ✅​

Phase 6: Update Standard Mekara Workflow ✅​

Phase 7: Standardize Design Document Terminology ✅​

Phase 8: Update Standard Mekara Project Documentation and Scripts ✅​

Phase 9: Verification ✅​

Notes​

Introduction

Objectives

Architecture

Design Details

File Organization Principles

Symlink Strategy

Invariants

Implementation Plan

Phase 1: Docusaurus Configuration ✅

Phase 2: Standards Reorganization ✅

Phase 3: Complete Standards Section ✅

Phase 4: Restructure Scripts Directory ✅

Phase 5: Create Wiki as Documentation Copy ✅

Phase 6: Update Standard Mekara Workflow ✅

Phase 7: Standardize Design Document Terminology ✅

Phase 8: Update Standard Mekara Project Documentation and Scripts ✅

Phase 9: Verification ✅

Notes