[Bug]: docs: overhaul docs/README.md layout for flat-file automation

[Yuvraj-Sarathe]

Bug Description

Problem Statement

The current docs/README.md file contains outdated markdown table structures and relative links pointing to nested folders (e.g., ./show/README.md) that have been deleted. If the new changelog.yml automated workflow triggers with this layout intact, appending new bulleted release entries directly under the existing static table will corrupt the file formatting and break markdown rendering on GitHub.

Proposed Solution

Overwrite the current docs/README.md with a clean, normalized baseline that removes the static table and establishes a pure unordered list (*) syntax under the ## Version History header. This will allow the automated shell script's compilation engine to append incoming tags seamlessly.

To-Do Checklist

• Remove the core **Version:** v1.2.1 static header to allow for dynamic automation titles.
• Strip out the broken subfolder navigation links in the Command Index and format them as standard code strings (show, health, etc.).
• Remove the markdown table element under ## Version History.
• Populate a clean, flat unordered list structure for existing legacy versions (v1.2.1 and v1.1.0) as a tracking baseline.

Steps to Reproduce

1. Leave the current docs/README.md file as-is with its static markdown table under the ## Version History header.
2. Ensure the newly updated changelog.yml workflow file is pushed to the repository branch.
3. Push a new semantic release tag (e.g., v1.2.2-test) to the remote repository to trigger the event-driven GitHub Actions runner.
4. Observe the runner execute the automated compilation step where it tries to append the newly generated flat markdown version files directly into docs/README.md.

Expected Behavior

The automated script should cleanly append the newly discovered flat markdown version files as a structured, bulleted list under the ## Version History section. The overall docs/README.md layout should remain completely valid, properly aligned, and highly readable on GitHub.

Actual Behavior

Because the current docs/README.md layout hardcodes a static markdown table layout (| Version | Release Date | Notes |), the automated script's loop will blindly inject raw bulleted strings (* [v1.2.2-test](v1.2.2-test.md)) directly into the bottom of the raw table formatting blocks. This breaks the Markdown interpreter syntax engine completely, resulting in a shredded, corrupted, and entirely unreadable wall of text at the bottom of the landing page.

Additionally, on a brand-new repository initialization where zero version files exist yet, the ls docs/v*.md glob will instantly crash with a non-zero exit status under GitHub Actions' strict set -e execution shell context, failing the pipeline completely before it can finish.

Environment

OS: GitHub Actions Runner (Ubuntu-Latest), Workflow Engine: GitHub Actions Core CI/CD Pipeline, Scripting Shell: GNU Bash (with set -e error-trapping enabled)

[utkarsh232005]

@Yuvraj-Sarathe does it increase the length of the readme when we append the historical versions?

[Yuvraj-Sarathe]

@Yuvraj-Sarathe does it increase the length of the readme when we append the historical versions?

Yes it does but it is just a few lines.

Something like this:

# Documentation (Latest: v1.4.0)

Published on: 2026-05-19

### Features
* Added robust JSON stream validation to the log monitoring daemon.
* Implemented live UI table resizing inside the watch module.

### Fixes
* Resolved memory leak on the telemetry socket handler when a pod forcefully evicts.

---

## Version History

* [v1.4.0](v1.4.0.md)
* [v1.3.1-alpha.1](v1.3.1-alpha.1.md)
* [v1.3.0](v1.3.0.md)
* [v1.2.2-test](v1.2.2-test.md)
* [v1.2.1](v1.2.1.md)
* [v1.1.0](v1.1.0.md)

[utkarsh232005]

okay looks good i am assigning you

[utkarsh232005]

@CodeRabbit plan

[utkarsh232005]

@Yuvraj-Sarathe check your github notification inbox

[coderabbitai]

Coding Plan

Summary

• Single-file edit to docs/README.md removing incompatible static elements (hardcoded version, markdown table, broken links)
• Normalize version history to a bulleted-list format matching the automated workflow's output pattern
• Preserve the Quick Start and Command Index sections' informational content while fixing their broken references

Implementation Steps

Normalize docs/README.md Layout

Update the documentation landing page to remove static/broken elements and establish a clean baseline compatible with the automated release workflow.

Task 1: Remove Static Version Header

Remove the hardcoded version line to allow dynamic automation titles.

• In docs/README.md, delete the **Version:** v1.2.1 line below the main title
• The main # KDM CLI — Versioned Command Documentation title can remain, as the workflow will overwrite it with its own dynamic title on first run

Task 2: Update Command Index Section

Convert broken subfolder navigation links to plain code-formatted strings.

• In docs/README.md, replace the five bulleted links under ## Command Index with non-linking code-formatted entries
• Change entries like [show](./show/README.md) to inline code format (e.g., `show`) with their descriptions preserved
• This removes the broken relative links while retaining the command reference information

Task 3: Replace Version History Table with Bulleted List

Remove the markdown table and establish a clean flat list structure for version tracking.

• In docs/README.md, delete the entire markdown table under ## Version History (including the header row | Version | Release Date | Notes | and separator row)
• Add two bulleted list entries as the baseline tracking structure:
  • * [v1.2.1](v1.2.1.md) — placeholder for current release
  • * [v1.1.0](v1.1.0.md) — placeholder for initial release
• Use the * [version](version.md) format to match the exact syntax the changelog.yml workflow generates

🤖 Prompt for AI agents

Edit `docs/README.md` to remove incompatible static elements and normalize the
file structure for compatibility with the `changelog.yml` automated release
workflow.

- **Remove the static version header:** Delete the `**Version:** v1.2.1` line
that appears below the main `# KDM CLI — Versioned Command Documentation` title.
Leave the title itself in place.
- **Update the Command Index section:** Under `## Command Index`, replace each
of the five bulleted links (e.g., `[show](./show/README.md)`) with inline
code-formatted entries (e.g., `` `show` ``), preserving each command's
description text. Do not remove the section or its descriptions — only fix the
broken link syntax.
- **Replace the Version History table with a bulleted list:** Delete the entire
markdown table under `## Version History`, including the `| Version | Release
Date | Notes |` header row and its separator row. Replace it with the following
two bulleted entries using the `* [version](version.md)` format:
  - `* [v1.2.1](v1.2.1.md)`
  - `* [v1.1.0](v1.1.0.md)`

This format must exactly match the syntax generated by the `changelog.yml`
workflow.

Research

The docs/ directory contains only docs/README.md, a 42-line hand-authored landing page with three sections: Command Index (5 broken relative links to non-existent subdirectories), Quick Start (bash code block), and Version History (a 3-column markdown table with placeholder dates). The .github/workflows/changelog.yml workflow completely rebuilds docs/README.md from scratch on each tagged release, generating a bulleted list of version files under a ## Version History header. The current table-based format is incompatible with this automation and must be normalized to a flat bulleted-list structure.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Edit `docs/README.md` to remove incompatible static elements and normalize the
file structure for compatibility with the `changelog.yml` automated release
workflow.

- **Remove the static version header:** Delete the `**Version:** v1.2.1` line
that appears below the main `# KDM CLI — Versioned Command Documentation` title.
Leave the title itself in place.
- **Update the Command Index section:** Under `## Command Index`, replace each
of the five bulleted links (e.g., `[show](./show/README.md)`) with inline
code-formatted entries (e.g., `` `show` ``), preserving each command's
description text. Do not remove the section or its descriptions — only fix the
broken link syntax.
- **Replace the Version History table with a bulleted list:** Delete the entire
markdown table under `## Version History`, including the `| Version | Release
Date | Notes |` header row and its separator row. Replace it with the following
two bulleted entries using the `* [version](version.md)` format:
  - `* [v1.2.1](v1.2.1.md)`
  - `* [v1.1.0](v1.1.0.md)`

This format must exactly match the syntax generated by the `changelog.yml`
workflow.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!