docs: improve documentation readability and formatting

[kxzk]

TL;DR

Add a docs index, delete internal-only directories, and fix broken links across all guides.

Why

The docs/ directory had no entry point, inconsistent footer sections, broken ../README.md links, and two internal subdirectories (design-history/, future-enhancements/) that shouldn't be published. This cleans it all up with a consistent "See Also" pattern and a new table of contents.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds docs/README.md as an entry-point table of contents for the documentation, standardizes guide footers to a consistent "See Also" cross-reference pattern (removing broken ../README.md references), and removes internal-only documentation directories (docs/design-history/, docs/future-enhancements/) from the published docs set.

The changes are primarily documentation navigation/structure updates: guides now point to other guides and the API reference, with docs/README.md intended to act as the central index for readers.

Confidence Score: 4/5

• This PR is generally safe to merge, but has a documentation navigation regression in Getting Started that should be corrected.
• Most changes are link/formatting cleanups and removal of internal-only docs. The main concern is that docs/GETTING_STARTED.md drops multiple relevant cross-links (Datasets/Experiments/Caching/API Reference), making the primary onboarding doc less connected to the rest of the guide set introduced by docs/README.md.
• docs/GETTING_STARTED.md

Important Files Changed

Filename	Overview
docs/ARCHITECTURE.md	Replaced Future Enhancements/Additional Resources/Questions footer with a standardized "See Also" section linking to other docs (including API_REFERENCE.md).
docs/CACHING.md	Replaced "Additional Resources" and "Questions" footer with "See Also" links; removed link to ../README.md and re-pointed to relevant internal guides.
docs/GETTING_STARTED.md	Renamed "Next Steps" to "See Also" but removed several cross-links (Datasets, Experiments, Caching, API reference) while leaving only Rails, reducing discoverability and conflicting with new docs/README index.
docs/MIGRATION.md	Standardized footer to "See Also" and updated links to Getting Started, Rails, Prompts, Caching, and Langfuse docs.
docs/RAILS.md	Standardized footer to "See Also" and updated cross-links to Getting Started, Configuration, Tracing, Migration, and Langfuse docs.
docs/README.md	Added new docs index (table of contents) linking to foundational, core feature, evaluation, production, and reference guides.
docs/TRACING.md	Renamed "Resources" to "See Also" and added internal cross-links (Scoring, Prompts, Rails, API reference) above external references.
docs/design-history/TRACING_DESIGN.md	Deleted internal design-history draft document from published docs set.
docs/design-history/langfuse-ruby-prompt-management-design.md	Deleted internal prompt management design document from published docs set.
docs/future-enhancements/STALE_WHILE_REVALIDATE_DESIGN.md	Deleted internal future-enhancements SWR design doc from published docs set.

Sequence Diagram

sequenceDiagram
  autonumber
  participant Reader as Reader
  participant DocsIndex as docs/README.md
  participant Guide as Feature Guide (e.g., GETTING_STARTED.md)
  participant Related as Related Guides

  Reader->>DocsIndex: Open documentation index
  DocsIndex-->>Reader: Links to Foundations/Core/Evaluation/Production/Reference
  Reader->>Guide: Follow link to a guide
  Guide-->>Reader: Content + standardized "See Also" footer
  Reader->>Related: Navigate via "See Also" cross-references
  Related-->>Reader: Continue exploring docs

Loading

[greptile-apps]

_{10 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[Copilot]

Pull request overview

This PR improves the published documentation set by adding an entry-point index, standardizing footer navigation to a “See Also” section, and removing internal-only design docs that shouldn’t ship.

Changes:

• Add docs/README.md as a docs index / table of contents.
• Standardize several guides’ footer sections to a “See Also” pattern and update internal cross-links.
• Remove internal-only documentation under docs/design-history/ and docs/future-enhancements/.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/future-enhancements/STALE_WHILE_REVALIDATE_DESIGN.md	Remove internal-only future enhancement design doc from published docs.
docs/design-history/langfuse-ruby-prompt-management-design.md	Remove internal-only design-history doc from published docs.
docs/design-history/TRACING_DESIGN.md	Remove internal-only tracing design doc from published docs.
docs/TRACING.md	Rename footer section to “See Also” and add cross-links to related guides.
docs/README.md	Add docs landing page/index linking to major guides.
docs/RAILS.md	Rename footer section to “See Also” and replace broken ../README.md reference with in-docs links.
docs/MIGRATION.md	Rename footer section to “See Also” and replace broken ../README.md reference with in-docs links.
docs/GETTING_STARTED.md	Rename “Next Steps” section to “See Also” and trim/reorder suggested follow-ups.
docs/CACHING.md	Rename footer section to “See Also” and remove obsolete “Questions?” block in favor of cross-links.
docs/ARCHITECTURE.md	Remove references to deleted internal-only directories and replace with “See Also” cross-links.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.