# Design: Storytelling Docs Redesign + Rename History

**Date:** 2026-03-04  
**Status:** Approved

## Context

The project was renamed from `code-explorer` to `codescout` across multiple commits. The rename is
complete in code, but there is no user-facing explanation of why it happened or what existing users
need to update. The current documentation is also mechanical — feature lists, bullet points, no
narrative voice.

## Goals

1. Document the rename for **both audiences**: existing `code-explorer` users who need to migrate,
   and new readers who just want to understand where the name comes from.
2. Keep the README clean — no changelog noise there.
3. Make the story feel written by a person, not generated by a diff tool.

## Approach: Manual-first, CHANGELOG as summary (Option C)

### `CHANGELOG.md` (new, repo root)

Lean and scannable. One entry for now. Points to the manual for depth.

```markdown
# Changelog

## [0.2.0] — codescout

> **TL;DR:** The project was renamed from `code-explorer` to `codescout`.
> Update your MCP config: replace `code-explorer` with `codescout` everywhere.
> [Full story and migration guide →](docs/manual/src/history.md)

### Breaking changes
- Binary renamed: `code-explorer` → `codescout`
- MCP server ID renamed accordingly
- 9 tools renamed for consistency (`get_symbols_overview` → `list_symbols`, etc.)
- 3 tools consolidated into unified interfaces
```

### `docs/manual/src/history.md` (new)

The full narrative page. Sections:

1. **TL;DR** — 3-4 bullet migration facts, scannable for the impatient
2. **The name** — why it changed: `code-explorer` was taken on crates.io, and the name had
   already started to feel too small. The tool now has persistent memory, semantic search, a
   dashboard, shell integration — it scouts your codebase, it doesn't just explore files.
3. **What grew** — 1 short paragraph on the arc: started as file navigation, grew into LSP
   symbol intelligence, then embeddings, then memory, then shell integration. The scope changed
   the identity.
4. **Migrating** — practical table: what to update (MCP config key, binary name, scripts).
5. **What else changed** — 2-3 bullet lines on tool renames and consolidations, linking to the
   tools reference.

Voice: direct but personal — written as if explaining to a colleague, not a PR description.

### `docs/manual/src/SUMMARY.md`

Add `history.md` to the manual's table of contents under a new top-level entry
(e.g. after "Getting Started").

## Out of Scope

- Rewriting the README narrative (separate task if wanted later)
- Versioning policy or semver decisions
- Documenting tool renames exhaustively (just a brief mention + link)
