# Documentation Audit — Fresh 0.2.9 → 0.2.13

Audit date: 2026-03-06

This document classifies all docs by status and lists items that need
manual/thresh validation before the documentation can be considered correct.

---

## 1. Internal docs reorganization

### `docs/architecture.md` — KEEP at top level

This is the main entry point for developers who want to learn how Fresh is
built. It's developer-facing but intentionally prominent. It may need updates
(e.g. for the plugin `registerHandler()` pattern, hanging line wrap in the
rendering pipeline, `BulkEdit` in the event model) but should stay where it is.

### Unified design decisions document — CREATED

`docs/internal/design-decisions.md` coalesces the key decisions, trade-offs,
and rationale from all shipped design docs into a single audit trail. This
preserves the *why* behind architectural choices without requiring readers to
find and cross-reference 20+ individual files.

### Shipped design docs — REMOVED

15 shipped design documents have been removed. Their key decisions,
trade-offs, and rationale are preserved in `design-decisions.md`:

`timesource-design.md`, `bulk-edit-optimization.md`, `cli-redesign.md`,
`FUZZY_FILE_FINDER_UX.md`, `encoding-support-design.md`, `paste-handling.md`,
`session-persistence-design.md`, `i18n-design.md`,
`per-buffer-view-state-design.md`, `config-design.md`,
`config-implementation-plan.md`, `plugin-architecture-plan.md`,
`vi-mode-design.md`, `warning-notification-ux.md`,
`markdown-compose-vs-glow.md`

### Duplicate files — REMOVED

- `SSH_REMOTE_EDITING_DESIGN.md` (removed) — kept `ssh-remote-editing-design.md`
- `PLUGIN_MARKETPLACE_DESIGN.md` (removed) — kept `plugin-marketplace-design.md`

### Remaining internal docs

**Active design/planning docs (in progress):**

| File | Status |
|------|--------|
| `code-tour-design.md` | Implementation phase; needs 4 new plugin API methods |
| `config-editor-design.md` | Design phase; built-in settings UI to replace plugin |
| `UNIFIED_UI_FRAMEWORK_PLAN.md` | In progress; extract shared controls library |
| `ISSUES_IMPLEMENTATION_PLAN.md` | Active; 14 prioritized bugs/improvements |
| `markdown.md` | Remaining compose mode work (column guides, context-sensitive Enter) |
| `io-separation-plan.md` | In progress; WASM compatibility refactoring |
| `visual-layout-unification.md` | Design complete; awaiting prioritization |
| `input-calibration-wizard.md` | Design complete; implementation pending |
| `plugin-marketplace-design.md` | Phase 1 done; Phase 2+ pending |
| `ssh-remote-editing-design.md` | Design complete; implementation phases pending |
| `finder-abstraction.md` | Plans 87% code reduction across finder plugins |
| `diff-view.md` | Partially implemented; CompositeBuffer architecture |
| `scroll-sync-design.md` | Partially implemented; marker-based sync |
| `editor-state-refactoring.md` | Partially complete; remaining extractions |
| `search-next-occurrence.md` | Design (not yet shipped) |
| `theme-consolidation-plan.md` | Design (not yet shipped) |
| `typora-seamless-canvas-plan.md` | Remaining compose implementation details |

**Process & quality docs:**

| File | Purpose |
|------|---------|
| `code-review.md` | Code quality issues list (31+ items); refactoring debt tracker |
| `testing.md` | Testing guidelines; EditorTestHarness docs |
| `usability-test-plan.md` | Usability testing methodology |
| `plugin-usability-review.md` | Plugin UX bugs and improvements (P0-P2) |
| `settings-controls-usability-report.md` | Settings UI bugs; critical data loss issue |
| `settings-modified-indicator-design.md` | Modified indicator semantics fix |
| `INPUT_LAYOUT_RENDERING_SUMMARY.md` | Architecture analysis; refactoring opportunities |

**Reference docs:**

| File | Purpose |
|------|---------|
| `event-dispatch-architecture.md` | Hit testing evolution plan (3 phases) |
| `terminal.md` | Incremental scrollback architecture |
| `theme-user-flows.md` | User flow documentation for theme system |
| `theme-usability-improvements.md` | Priority matrix from usability testing |
| `unicode-width.md` | Unicode width handling reference |
| `remote-filesystem-optimization.md` | Remote FS optimization strategies |

---

## 2. User-facing docs that need UPDATES for 0.2.9–0.2.13 features

### `docs/features/lsp.md` — HIGH priority

Missing documentation for:

- **LSP Environment Variables** (0.2.13) — pass env vars to LSP server binaries
  via config
- **LSP Language ID Overrides** (0.2.13) — `language_id_overrides` in LSP server
  config
- **Rust LSP Mode Switching** (0.2.13) — command palette action to switch
  full / reduced-memory rust-analyzer
- **`restartLspForLanguage`** plugin API (0.2.13)
- **Process limits** for `registerLspServer` (0.2.13)
- **Disabled LSP start/restart commands** for languages without LSP config
  (0.2.13)
- **Inline Diagnostics** (0.2.13) — diagnostic text at end of line, enable in
  Settings UI

### `docs/features/editing.md` — HIGH priority

Missing documentation for:

- **Hanging Line Wrap** (0.2.13) — wrapped continuation lines preserve parent
  indentation
- **Auto-Close Config** (0.2.12) — separate `auto_close` toggle, per-language
  overrides via `languages.<lang>.auto_close`
- **Surround Selection** (0.2.12) — typing delimiter with selection wraps it
- **Smart Quote Suppression** (0.2.12) — quotes inside strings don't auto-close
- **Read-Only Mode** (0.2.12) — auto-detection for library/toolchain paths,
  toggle command, `[RO]` status bar indicator
- **Whitespace Indicators** (0.2.11) — granular per-position control (leading,
  inner, trailing) for spaces and tabs
- **Indent-Based Code Folding** (0.2.11) — folding without LSP, works in large
  file mode
- **Signature Help** rendering improvements (0.2.13) — markdown in popups

Also has leftover `TODO` comments on lines ~105, ~107.

### `docs/features/themes.md` — MEDIUM priority

Missing:

- **Theme Editor Redesign** (0.2.13) — virtual scrolling, mouse support,
  flicker-free inline styling
- **"Inspect Theme at Cursor"** command (0.2.13)
- **Ctrl+Right-Click theme info popup** (0.2.13)
- **`whitespace_indicator_fg`** theme color (0.2.11)

### `docs/features/command-palette.md` — MEDIUM priority

Missing:

- **Open File Jump** (0.2.13) — `path:line[:col]` syntax in Open File prompt
  and Quick Open

### `docs/plugins/index.md` — HIGH priority

Missing:

- **Load Plugin from Buffer** (0.2.13) — run & hot-reload plugins from an open
  buffer with LSP support
- **Plugin API `registerHandler()`** (0.2.13) — replacing `globalThis` pattern
- **`restartLspForLanguage`** and **async `reloadGrammars()`** (0.2.13)
- **Strict TypeScript** requirement across all plugins (0.2.13)
- **Plugin API v2** (0.2.4) — `createTerminal`, `sendTerminalInput`,
  `closeTerminal`, `getAllCursors`, plugin state API

### `docs/configuration/index.md` — MEDIUM priority

Missing from editor settings reference:

- `auto_close` toggle and per-language overrides (0.2.12)
- `auto_surround` config (0.2.12)
- Whitespace indicator settings (0.2.11)
- LSP `language_id_overrides` (0.2.13)
- LSP environment variables (0.2.13)
- `show_status_bar` toggle (0.2.13)
- `diagnostics_inline_text` setting (0.2.13)

### `docs/features/file-explorer.md` — LOW priority

Missing:

- Quick search (type to filter) — shipped pre-0.2.9 but never documented

### `docs/features/terminal.md` — LOW priority

Minor:

- Bracket paste mode fixes (0.2.5, 0.2.13) — user-visible in client/server
  sessions

### `docs/getting-started/index.md` — LOW priority

- Could benefit from `path:line:col` syntax examples and a mention of session
  mode (`fresh -a`)

### `docs/architecture.md` — LOW priority

May need updates for:
- `registerHandler()` plugin pattern (replacing `globalThis`)
- `BulkEdit` event type in the Action → Event section
- Hanging line wrap in rendering pipeline description
- Non-blocking grammar builds (background thread)

### Blog posts — NO ACTION NEEDED

Blog posts are point-in-time snapshots. They are accurate for the versions they
describe and don't need retroactive updates.

---

## 3. Validation checklist — things to verify with thresh / manual testing

Each item below should be confirmed to work as documented (or as we plan to
document) before publishing updated docs.

### LSP features (test with a Rust and a TypeScript project)

- [ ] **LSP env vars**: Add `"env": {"FOO": "bar"}` to an LSP server config in
  `config.json`, verify the LSP process receives it (e.g. use a shell wrapper
  that prints env)
- [ ] **Language ID overrides**: Set `"language_id_overrides": {"tsx": "typescriptreact"}`
  and verify the LSP receives the overridden language ID on `textDocument/didOpen`
- [ ] **Rust LSP mode switching**: Open a Rust project, use command palette to
  switch between Full and Reduced Memory modes, confirm rust-analyzer restarts
  with appropriate config
- [ ] **Inline diagnostics**: Enable "diagnostics inline text" in Settings UI,
  trigger an error, verify diagnostic text appears at end of line. Verify
  staleness dropping (edit the line, confirm diagnostic fades/disappears)
- [ ] **Disabled LSP commands**: Open a file with no LSP config (e.g. plain
  text), confirm "Start LSP" / "Restart LSP" commands are disabled/hidden in
  command palette
- [ ] **Signature help markdown**: Open a TypeScript file, trigger signature
  help (type a function call), verify markdown renders correctly in popup

### Editing features

- [ ] **Hanging line wrap**: Enable line wrap, open a file with indented code,
  resize window so lines wrap — verify continuation lines preserve parent
  indent level
- [ ] **Auto-close config**: Set `"auto_close": false` in config, verify
  brackets/quotes no longer auto-close. Test per-language override:
  `"languages": {"markdown": {"auto_close": false}}`
- [ ] **Surround selection**: Select text, type `(` — verify it wraps to
  `(selection)`. Test with `[`, `{`, `"`, `'`
- [ ] **Smart quote suppression**: Position cursor inside a string, type `"` —
  verify it inserts one quote, not two
- [ ] **Read-only mode**: Open a file from `/usr/include` or a rustup toolchain
  path — verify `[RO]` appears and edits are blocked. Test "Toggle Read Only"
  command to override
- [ ] **Whitespace indicators**: Configure `"whitespace": {"space": {"leading": true, "inner": false, "trailing": true}}` — verify dots appear only in
  leading/trailing positions
- [ ] **Indent-based code folding**: Open a Python file (no LSP), verify fold
  indicators appear in gutter based on indentation. Test fold/unfold via
  gutter click and command palette

### Theme features

- [ ] **Theme editor virtual scrolling**: Open theme editor with a theme that
  has many fields — verify smooth scrolling, no flicker
- [ ] **Theme editor mouse support**: Click on color fields in theme editor,
  verify mouse interaction works
- [ ] **Inspect Theme at Cursor**: Place cursor on colored text, run "Inspect
  Theme at Cursor" from command palette — verify it shows the theme scope/color
- [ ] **Ctrl+Right-Click**: Right-click with Ctrl on colored text, verify theme
  info popup appears
- [ ] **`whitespace_indicator_fg`**: Add this key to a custom theme, verify
  whitespace indicators use the custom color

### Plugin API

- [ ] **Load Plugin from Buffer**: Open a `.ts` file with plugin code, run
  "Load Plugin from Buffer" command — verify plugin activates. Edit the file,
  verify hot-reload works
- [ ] **LSP in plugin dev buffers**: While editing a plugin buffer, verify
  TypeScript LSP completions work (e.g. `fresh.` should autocomplete API
  methods)
- [ ] **`registerHandler()`**: Write a plugin using `registerHandler()` instead
  of `globalThis`, verify it works
- [ ] **`restartLspForLanguage()`**: Call from a plugin, verify the LSP for that
  language restarts
- [ ] **`reloadGrammars()`**: Call async `reloadGrammars()` from a plugin,
  verify syntax highlighting refreshes
- [ ] **Process limits**: Set `process_limits` in `registerLspServer()` config,
  verify the LSP process respects memory/CPU limits

### Command palette / navigation

- [ ] **Open File Jump**: Type `src/main.rs:42` in Open File prompt — verify it
  opens the file at line 42. Test `src/main.rs:42:10` for column positioning
- [ ] **Status bar toggle**: Run "Toggle Status Bar" from command palette,
  verify it hides. Run again, verify it shows. Check config persists across
  restart

### Configuration

- [ ] **All new config keys**: Verify each new config key listed in section 2
  is accepted by Fresh without errors and has the documented effect
- [ ] **Settings UI**: Verify new settings (inline diagnostics, auto_close,
  auto_surround, whitespace indicators, show_status_bar) appear in the
  Settings UI with correct types and descriptions

---

## 4. Summary of work needed

| Priority | Category | Items |
|----------|----------|-------|
| **High** | Doc updates | `features/lsp.md`, `features/editing.md`, `plugins/index.md` |
| **Medium** | Doc updates | `features/themes.md`, `features/command-palette.md`, `configuration/index.md` |
| **Low** | Doc updates | `features/file-explorer.md`, `features/terminal.md`, `getting-started/index.md`, `architecture.md` |
| **Done** | Internal reorg | Unified `design-decisions.md` created; duplicates removed |
| **Validation** | Thresh/manual | 25 test items across 5 categories |
