ehud-am · ehud-am · Apr 4, 2026 · Apr 4, 2026 · Apr 4, 2026 · Apr 4, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -16,6 +16,9 @@ Auto-generated from all feature plans. Last updated: 2026-04-04
 - No database; runtime state comes from local filesystem metadata, git metadata, build/package metadata, URL state, and in-memory server state (005-version-line-numbers)
 - TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, @tanstack/react-query, Vite 7, Vitest, React Testing Library, esbuild (006-manual-file-editing)
 - No database; runtime state is derived from the local filesystem, git metadata, browser URL state, and in-memory server/UI state (006-manual-file-editing)
+- TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, Vite 7, Vitest, React Testing Library, esbuild (007-editor-empty-repo)
+- TypeScript 5.x on Node.js 22+ + Hono, React 18, Vite 7, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, Vitest, React Testing Library (007-editor-empty-repo)
+- None; runtime state is derived from local filesystem metadata, git metadata, browser URL state, and in-memory server/UI state (007-editor-empty-repo)
 
 ## Project Structure
 
@@ -41,9 +44,9 @@ npm run verify # Run tests, builds, and dependency audits
 TypeScript 5.x + Node.js 22+: follow standard conventions. Use `.js` extensions on all imports (NodeNext module resolution). No Go, no Makefile, no shell scripts.
 
 ## Recent Changes
-- 006-manual-file-editing: Added TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, @tanstack/react-query, Vite 7, Vitest, React Testing Library, esbuild
-- 005-version-line-numbers: Added TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, Vite 7, react-markdown, rehype-highlight, highlight.js, Vitest, React Testing Library, esbuild
-- 004-copy-control-polish: Added TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, Vite 7, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, highlight.js, Vitest, esbuild
+- 007-editor-empty-repo: Added TypeScript 5.x on Node.js 22+ + Hono, React 18, Vite 7, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, Vitest, React Testing Library
+- 007-editor-empty-repo: Added TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, Vite 7, Vitest, React Testing Library, esbuild
+- 007-editor-empty-repo: Added TypeScript 5.x on Node.js 22+ for server and CLI, TypeScript + React 18 for the UI + Hono, @hono/node-server, React 18, @tanstack/react-query, Vite 7, Vitest, React Testing Library, esbuild
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.4.6
+
+- Reserved the next release version for the upcoming editor workspace and empty-repository UX improvements captured in `007-editor-empty-repo`.
+
 ## 0.4.5
 
 - Added manual local file creation, in-place editing, and deletion flows in the repository viewer with dirty-state protection and sync-aware refresh behavior.

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gitlocal",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Browse any local git repository in your browser",
   "keywords": [
     "git",

diff --git a/specs/007-editor-empty-repo/checklists/requirements.md b/specs/007-editor-empty-repo/checklists/requirements.md
@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Editor Workspace and Empty Repo UX
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-04-04  
+**Feature**: [/Users/ehudamiri/Documents/projects/gitlocal/specs/007-editor-empty-repo/spec.md](/Users/ehudamiri/Documents/projects/gitlocal/specs/007-editor-empty-repo/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation pass 1: All checklist items passed.
+- The spec covers two primary flows: expanding the editing workspace and improving the repository landing experience when no README is present.
+- No clarifications were required because the requested behavior changes are well bounded and reasonable defaults were available.
diff --git a/specs/007-editor-empty-repo/contracts/content-panel-navigation.md b/specs/007-editor-empty-repo/contracts/content-panel-navigation.md
@@ -0,0 +1,64 @@
+# Content Panel Navigation Contract
+
+## Repository Info Contract
+
+- `GET /api/info` continues to return the current repository identity and viewer mode payload.
+- The payload includes lightweight repository-state metadata:
+  - `hasCommits`: whether the opened repository has at least one reachable commit.
+  - `rootEntryCount`: number of immediate repository-root entries available for browsing.
+- Success expectations:
+  - Freshly initialized repositories with no commits return `hasCommits: false`.
+  - Repositories with browseable root content return `rootEntryCount > 0` even when no `README` is present.
+
+## README Discovery Contract
+
+- `GET /api/readme` continues to return `{ path: string }`.
+- An empty `path` means no default `README` was found for the repository.
+- The absence of a `README` must not force a dedicated custom recovery panel in the main content area.
+
+## Main Panel Folder View Contract
+
+- When no file is selected, the main content area renders the current folder's immediate child files and folders.
+- When the selected path is a folder, the main content area renders that folder using the same folder-list presentation model.
+- The folder list must:
+  - List immediate children only.
+  - Provide an explicit `Open` action on the right side of each row.
+  - Support opening a row item by double-clicking it.
+  - Reuse a similar visual style and interaction feel to the existing non-git folder browser.
+  - Show an intentional empty-folder message when there are no visible child entries.
+- Recursive expansion remains the responsibility of the left tree; the main panel stays single-level for the active folder.
+
+## Main Panel Recovery Behavior Contract
+
+- The main content area must not render the prior "Pick up where you left off" recovery message or an equivalent dedicated recovery panel.
+- If repository-switch logic clears a stale file selection, the main panel falls back to the current folder list instead of a custom recovery state.
+- Any existing status or reset banner outside the main panel may remain, but it must not block or replace the folder list.
+
+## Edit Workspace Layout Contract
+
+- Entering edit mode keeps the user in the main content panel.
+- The edit workspace must:
+  - Use most of the panel width available in desktop layouts.
+  - Present the textarea at a substantially larger default height than the previous implementation.
+  - Keep cancel and save controls visible and understandable.
+- The responsive layout may stack controls differently on smaller screens, but it must not regress to the previous cramped presentation at common desktop widths.
+
+## Rendered Markdown Contract
+
+- Rendered markdown presentation must not display markdown comments or other hidden comment-style content.
+- Raw mode continues to show the original markdown source unchanged.
+- Comment suppression applies only to rendered presentation, not to file storage or raw viewing.
+
+## Test Coverage Contract
+
+- UI tests must cover:
+  - Expanded editor presentation and visible action controls.
+  - Main-panel folder list as the default fallback when no file is selected.
+  - Folder list row behavior for explicit `Open` actions and double-click navigation.
+  - Visual/structural consistency expectations with the existing non-git folder browser.
+  - Empty-folder messaging in the main content area.
+  - Hidden-comment suppression in rendered markdown while raw mode remains unchanged.
+- Backend tests must cover:
+  - Repository info metadata for repos with and without commits.
+  - Root entry counting for repositories with browseable content.
+  - Directory-list behavior needed by the main-panel folder view.
diff --git a/specs/007-editor-empty-repo/data-model.md b/specs/007-editor-empty-repo/data-model.md
@@ -0,0 +1,84 @@
+# Data Model: Editor Workspace, Folder-First Main View, and Markdown Comment Hiding
+
+## Edit Workspace State
+
+- **Description**: The UI state that controls how the content panel presents an editable file and how much of the viewport is allocated to the editing surface.
+- **Fields**:
+  - `mode`: `view`, `edit`, `create`, or `confirm-delete`.
+  - `selectedPath`: Repository-relative file path currently shown in the panel.
+  - `canMutateFiles`: Whether file-editing actions are allowed in the current repository context.
+  - `busy`: Whether a save, create, or delete action is in progress.
+  - `error`: User-displayable error copy for the current editing session.
+- **Validation rules**:
+  - Expanded editor layout applies only when `mode` is `edit` or `create`.
+  - Primary save and cancel actions remain visible in supported desktop widths.
+- **Relationships**:
+  - Owned by the content panel UI.
+  - Uses existing file read and mutation flows.
+
+## Repository Summary
+
+- **Description**: Lightweight server-provided metadata used to describe the currently opened repository and seed folder-first navigation behavior.
+- **Fields**:
+  - `name`: Repository display name.
+  - `path`: Opened repository path.
+  - `currentBranch`: Current working-tree branch name, if any.
+  - `isGitRepo`: Whether the opened folder is a valid git repository.
+  - `pickerMode`: Whether the app is currently in folder-picker mode.
+  - `version`: Running application version.
+  - `hasCommits`: Whether the repository has at least one reachable commit.
+  - `rootEntryCount`: Count of immediate browseable entries at the repository root.
+- **Validation rules**:
+  - `rootEntryCount` excludes `.git` internals and any path outside the repository boundary.
+  - `hasCommits` remains false for a freshly initialized repository with no commits.
+- **Relationships**:
+  - Returned by the repository info contract.
+  - Combined with current folder data to determine sensible default main-panel behavior.
+
+## Main Panel Directory View State
+
+- **Description**: The normalized content-panel state shown when no file is selected or when the selected path is a folder.
+- **Fields**:
+  - `folderPath`: Repository-relative folder path currently represented in the main panel.
+  - `entries`: Immediate child files and folders visible inside that folder.
+  - `empty`: Whether the folder has no visible child entries.
+  - `origin`: `default-folder-view` or `selected-folder-view`.
+  - `supportsDoubleClick`: Whether row double-click opens the underlying item.
+  - `rowActionLabel`: Visible action text shown on each row, expected to be `Open`.
+- **Validation rules**:
+  - `entries` include only immediate children, not recursive descendants.
+  - Hidden repository internals must not appear.
+  - Each entry exposes both row-level double-click behavior and an explicit action button.
+  - Empty folders render an intentional empty state instead of an error presentation.
+- **Relationships**:
+  - Derived from tree or directory-list data for the current folder context.
+  - Rendered by the content panel when the main view should show browseable items instead of a file.
+
+## Directory Entry
+
+- **Description**: A single browseable item shown in the main-panel folder list.
+- **Fields**:
+  - `path`: Repository-relative path for the item.
+  - `name`: Display name shown in the row.
+  - `type`: `file` or `dir`.
+  - `openTarget`: The path that should be opened when the row action or double-click is used.
+- **Validation rules**:
+  - `name` is the final path segment of `path`.
+  - `openTarget` must resolve within the current repository boundary.
+- **Relationships**:
+  - Produced from server tree/directory data.
+  - Consumed by the content panel folder list and its row interactions.
+
+## Rendered Markdown View
+
+- **Description**: The presentation-only version of markdown content shown when the user chooses rendered mode instead of raw mode.
+- **Fields**:
+  - `sourceContent`: Original markdown file text.
+  - `renderContent`: Sanitized markdown text or AST used for rendered presentation.
+  - `rawVisible`: Whether the viewer is currently showing raw source instead of rendered markdown.
+- **Validation rules**:
+  - Markdown comments intended to stay hidden must not appear in `renderContent`.
+  - Raw mode continues to show the original source unchanged.
+- **Relationships**:
+  - Produced by the markdown rendering path.
+  - Used only for rendered markdown presentation.
diff --git a/specs/007-editor-empty-repo/plan.md b/specs/007-editor-empty-repo/plan.md
@@ -0,0 +1,99 @@
+# Implementation Plan: Editor Workspace, Folder-First Main View, and Markdown Comment Hiding
+
+**Branch**: `007-editor-empty-repo` | **Date**: 2026-04-04 | **Spec**: [/Users/ehudamiri/Documents/projects/gitlocal/specs/007-editor-empty-repo/spec.md](/Users/ehudamiri/Documents/projects/gitlocal/specs/007-editor-empty-repo/spec.md)
+**Input**: Feature specification from `/Users/ehudamiri/Documents/projects/gitlocal/specs/007-editor-empty-repo/spec.md`
+
+## Summary
+
+Make the inline editor use the main content area more fully, hide markdown comments in rendered mode, and replace the current no-selection / folder-error experience with a folder-first content view in the main panel. When no primary file is selected, GitLocal should show the current folder's files and subfolders using a visual pattern consistent with the existing non-git folder browser, with an `Open` action on each row and double-click navigation.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.x on Node.js 22+  
+**Primary Dependencies**: Hono, React 18, Vite 7, @tanstack/react-query, react-markdown, remark-gfm, rehype-highlight, Vitest, React Testing Library  
+**Storage**: None; runtime state is derived from local filesystem metadata, git metadata, browser URL state, and in-memory server/UI state  
+**Testing**: Vitest, React Testing Library, integration tests via existing server test suite  
+**Target Platform**: Local desktop browser with Node-based local server  
+**Project Type**: Full-stack web application  
+**Performance Goals**: Preserve current interactive browsing responsiveness for repository and folder navigation  
+**Constraints**: Offline-capable, no database, GitHub-like browsing experience, >=90% per-file branch coverage  
+**Scale/Scope**: Single local repository or folder session with content-panel browsing, editing, and navigation
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- `Code quality`: Pass. The change fits the existing Hono + React codebase and can be implemented with typed server/client contracts plus focused tests.
+- `Test-first verification`: Pass. The work can be covered with backend metadata/directory tests and UI tests for editor expansion, folder list behavior, and markdown rendering behavior.
+- `Local-first product behavior`: Pass. All required signals come from local filesystem and git metadata already available to the app.
+- `Simplicity`: Pass. The plan extends the current content panel instead of introducing a new navigation surface or separate editor shell.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/007-editor-empty-repo/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── content-panel-navigation.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── handlers/
+│   └── git.ts
+├── git/
+│   ├── repo.ts
+│   └── tree.ts
+└── types.ts
+
+tests/
+├── integration/
+│   └── server.test.ts
+└── unit/
+    ├── git/
+    │   └── repo.test.ts
+    └── handlers/
+        └── git.test.ts
+
+ui/
+└── src/
+    ├── App.tsx
+    ├── App.css
+    ├── App.test.tsx
+    ├── services/
+    │   └── api.ts
+    ├── types/
+    │   └── index.ts
+    └── components/
+        └── ContentPanel/
+            ├── ContentPanel.tsx
+            ├── ContentPanel.test.tsx
+            ├── InlineFileEditor.tsx
+            └── MarkdownRenderer.tsx
+```
+
+**Structure Decision**: Keep the existing single server + single UI structure. Server work will extend repository metadata and folder listing support, while UI work will concentrate in the content panel, shared API/types, and styling/tests.
+
+## Phase 0: Research Focus
+
+- Confirm the minimum server metadata needed to choose between a selected file view and a folder-first main view.
+- Confirm how to reuse the existing non-git folder-browser look and interaction model inside the repository content panel without duplicating logic unnecessarily.
+- Confirm the safest rendered-markdown path for hiding comments only in rendered mode.
+
+## Phase 1: Design Focus
+
+- Define the normalized main-panel state when no file is selected, including current-folder list presentation and empty-folder messaging.
+- Define the server/client contract for directory entries, including enough information for per-row `Open` actions and double-click behavior.
+- Define responsive layout expectations for the larger inline editor so desktop space is used better without breaking smaller viewports.
+
+## Complexity Tracking
+
+No constitution violations are expected for this feature.