Skip to content

docs: Update architecture and planning documentation #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
randlee merged 3 commits into from
Jan 25, 2026
Merged

docs: Update architecture and planning documentation #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9174393
docs: clarify workspace storage and settings schema
randlee Jan 25, 2026
e667a24
docs: align master plan with current MVP scope
randlee Jan 25, 2026
17c3e31
docs: refresh phase 1 progress and effort totals
randlee Jan 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions docs/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,8 +301,11 @@ struct WorkspaceConfig {
```

**Storage:**
- Near-term: `~/.config/terminalg/workspaces/<workspace-id>.json`
- Long-term: `.terminalg/<workspace>.json` in project repos
- Near-term: platform config dir, e.g. macOS `~/Library/Application Support/terminalg/workspaces/<workspace-id>.json`, Linux `~/.config/terminalg/workspaces/<workspace-id>.json`, Windows `%APPDATA%\\terminalg\\workspaces\\<workspace-id>.json`
- Workspace-local: `.terminalg/<workspace>.json` in project repos

**Indexing:**
- App settings track all available workspaces and their config paths

**Files:** `src/settings/workspace.rs`

Expand All @@ -329,6 +332,12 @@ Views (apply settings)
4. Call `cx.notify()` on all views
5. Views apply new settings on next render

**Schema Versioning:**
- Settings include a schema version field
- On load, migrate older versions to the latest schema
- Unknown fields are ignored for forward compatibility
- Migration failures surface a user-facing error and fall back to defaults

**Details:** See `docs/architecture/settings-system.md`

---
Expand Down Expand Up @@ -591,7 +600,7 @@ cx.spawn(|view, mut cx| async move {
### 11.1 macOS (Primary Development Platform)

**PTY:** POSIX via Zed terminal (openpty, fork, execv)
**Config Path:** `~/.config/terminalg/` or `~/Library/Application Support/terminalg/`
**Config Path:** `~/Library/Application Support/terminalg/`
**Shell:** Default to `$SHELL` or `/bin/zsh`

### 11.2 Linux
Expand All @@ -607,7 +616,7 @@ cx.spawn(|view, mut cx| async move {
**Config Path:** `%APPDATA%\terminalg\`
**Shell:** Default to PowerShell or `cmd.exe`

**Note:** All platforms supported from Phase 1 using Zed's cross-platform terminal implementation. Primary development and testing on macOS, CI/testing on all platforms.
**Note:** Phase 1 validates the bootstrap app window on macOS, Linux, and Windows. Full cross-platform terminal functionality arrives in Phase 2 after Zed terminal integration. Primary development and testing on macOS, CI/testing on all platforms.

---

Expand Down
75 changes: 33 additions & 42 deletions docs/MASTER-PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

**Version:** 1.0
**Last Updated:** 2025-01-24
**Current Phase:** Phase 1 (70% complete)
**Current Phase:** Phase 1 (60% complete)

---

## 1. Overview

Development organized into 4 phases, each containing sprints that can be executed sequentially or in parallel where dependencies allow.
Development organized into 5 phases, each containing sprints that can be executed sequentially or in parallel where dependencies allow.

**Total Estimated Effort:** 90-130 hours
**Total Estimated Effort:** 80-110 hours
**Timeline:** 10-16 days full-time, or 2-3 weeks part-time

---
Expand All @@ -22,15 +22,15 @@ Development organized into 4 phases, each containing sprints that can be execute
2. Fully working Zed terminal
3. Add file/folder browser
4. Add markdown viewer (preview)
5. Markdown viewer + editing (post-MVP)
5. Markdown viewer + editing (MVP)

| Phase | Name | Status | Estimated Hours | Sprints |
|-------|------|--------|-----------------|---------|
| 1 | Foundation & Workspace | 70% | 20-25 | 4 |
| 1 | Foundation & Workspace | 60% | 20-25 | 5 |
| 2 | Zed Terminal Integration | Not Started | 20-30 | 3 |
| 3 | File/Folder Browser | Not Started | 15-20 | 2 |
| 4 | Markdown Viewer (MVP) | Not Started | 15-20 | 2 |
| 5 | Markdown Editor (Post-MVP) | Not Started | 10-15 | 2 |
| 4 | Markdown Viewer | Not Started | 15-20 | 2 |
| 5 | Markdown Editor (MVP) | Not Started | 10-15 | 2 |

---

Expand All @@ -40,7 +40,7 @@ Development organized into 4 phases, each containing sprints that can be execute

**Priority:** 1 - App framework w/ empty windows

**Status:** 70% complete (Settings ✓, Theme ✓, GPUI app + workspace pending)
**Status:** 60% complete (Settings ✓, Theme ✓, GPUI app + workspace pending)

**Dependencies:** None

Expand Down Expand Up @@ -90,7 +90,7 @@ Development organized into 4 phases, each containing sprints that can be execute

#### Sprint 1.4: GPUI Bootstrap ⏳ IN PROGRESS
**Duration:** 3-5 hours
**Status:** Ready to start
**Status:** In progress

**Detailed Checklist:** `docs/sprints/phase-1-sprint-4-gpui-bootstrap.md`

Expand Down Expand Up @@ -285,7 +285,7 @@ Development organized into 4 phases, each containing sprints that can be execute

---

## 6. PHASE 4: Markdown Viewer (MVP)
## 6. PHASE 4: Markdown Viewer

**Goal:** Implement markdown preview/rendering in document viewer pane.

Expand Down Expand Up @@ -332,7 +332,7 @@ Development organized into 4 phases, each containing sprints that can be execute
- [ ] Test: File browser → markdown viewer works
- [ ] Test: Link navigation works

### Phase 4 Checkpoint (MVP COMPLETE)
### Phase 4 Checkpoint

**Complete when:**
- [ ] Markdown viewer renders correctly
Expand All @@ -344,17 +344,17 @@ Development organized into 4 phases, each containing sprints that can be execute
- [ ] Theme applied to all components
- [ ] Workspace configuration persists everything

**🎉 MVP COMPLETE - All core features functional**
**Phase 4 COMPLETE - Markdown viewer functional**

---

## 7. PHASE 5: Markdown Editor (Post-MVP)
## 7. PHASE 5: Markdown Editor (MVP)

**Goal:** Add markdown editing capability with preview mode.

**Priority:** 5 - Markdown viewer + editing

**Status:** Not started (Post-MVP)
**Status:** Not started

**Dependencies:** Phase 1-4 complete

Expand Down Expand Up @@ -394,7 +394,7 @@ Development organized into 4 phases, each containing sprints that can be execute
- [ ] Test: Split view works
- [ ] Test: Scroll sync works

### Phase 5 Checkpoint
### Phase 5 Checkpoint (MVP COMPLETE)

**Complete when:**
- [ ] Markdown editing mode functional
Expand All @@ -404,7 +404,7 @@ Development organized into 4 phases, each containing sprints that can be execute
- [ ] Split view with scroll sync
- [ ] All editor features work correctly

**🎉 PHASE 5 COMPLETE - Markdown editing fully functional**
**🎉 MVP COMPLETE - Markdown editing fully functional**
- [ ] Add keyboard shortcut for theme cycling
- [ ] Test: URLs clickable
- [ ] Test: Settings hot-reload works
Expand Down Expand Up @@ -440,13 +440,13 @@ Phase 3 (File Browser)
└─ Sprint 3.2: File Browser Integration
↓ (all complete)

Phase 4 (Markdown Viewer - MVP)
Phase 4 (Markdown Viewer)
├─ Sprint 4.1: Markdown Viewer Core
↓
└─ Sprint 4.2: Markdown Viewer Integration
↓ (MVP COMPLETE) 🎉
↓

Phase 5 (Markdown Editor - Post-MVP)
Phase 5 (Markdown Editor - MVP)
├─ Sprint 5.1: Markdown Editor Core
↓
└─ Sprint 5.2: Editor/Preview Integration
Expand Down Expand Up @@ -488,14 +488,14 @@ Phase 5 (Markdown Editor - Post-MVP)
### In Progress

**Sprint 1.4:** GPUI Bootstrap
- Status: Ready to start
- Status: In progress
- Blockers: None
- Next step: Follow `docs/sprints/phase-1-sprint-4-gpui-bootstrap.md`

### Effort Summary

**Used:** 10-12 hours (Phase 1 foundation)
**Remaining:** 80-120 hours (Phases 1.4, 2, 3, 4)
**Remaining:** 70-100 hours (Phases 1.4, 2, 3, 4, 5)

---

Expand Down Expand Up @@ -784,27 +784,25 @@ All agents registered in: `.claude/agents/registry.yaml`

### Aggressive Schedule (Full-Time)

- **Phase 1:** 1.5-2 days (12-16 hours) - 70% done, 6-10 hours remaining → **v0.1.0**
- **Phase 1:** 1.5-2 days (12-16 hours) - 60% done, 8-12 hours remaining → **v0.1.0**
- **Phase 2:** 2.5-4 days (20-30 hours) → **v0.2.0**
- **Phase 3:** 2-3 days (15-20 hours) → **v0.3.0**
- **Phase 4:** 2-3 days (15-20 hours) → **v0.4.0** ← MVP features complete
- **Phase 5:** 1.5-2 days (10-15 hours) → **v0.5.0**
- **Phase 4:** 2-3 days (15-20 hours) → **v0.4.0**
- **Phase 5:** 1.5-2 days (10-15 hours) → **v0.5.0** ← MVP features complete
- **v1.0.0:** When validated as usable (TBD)

**Total (MVP features):** 8-12 days full-time (Phases 1-4) → v0.4.0
**Total (with editing):** 9.5-14 days full-time (Phases 1-5) → v0.5.0
**Total (MVP features):** 9.5-14 days full-time (Phases 1-5) → v0.5.0

### Realistic Schedule (Part-Time)

- **Phase 1:** 2-3 sessions - 70% done, 1-2 sessions remaining → **v0.1.0**
- **Phase 1:** 2-3 sessions - 60% done, 2 sessions remaining → **v0.1.0**
- **Phase 2:** 3-4 sessions → **v0.2.0**
- **Phase 3:** 2-3 sessions → **v0.3.0**
- **Phase 4:** 2-3 sessions → **v0.4.0** ← MVP features complete
- **Phase 5:** 2-3 sessions → **v0.5.0**
- **Phase 4:** 2-3 sessions → **v0.4.0**
- **Phase 5:** 2-3 sessions → **v0.5.0** ← MVP features complete
- **v1.0.0:** When validated as usable (TBD)

**Total (MVP features):** 9-13 sessions (~2-3 weeks) → v0.4.0
**Total (with editing):** 11-16 sessions (~3-4 weeks) → v0.5.0
**Total (MVP features):** 11-16 sessions (~3-4 weeks) → v0.5.0

---

Expand Down Expand Up @@ -833,22 +831,22 @@ All agents registered in: `.claude/agents/registry.yaml`
- Integrated with workspace config
- Keyboard navigation works

### Phase 4 Success (Markdown Viewer - MVP)
### Phase 4 Success (Markdown Viewer)
- Markdown viewer renders correctly
- Document tabs functional (multiple documents)
- File browser → document viewer integration works
- All three panes working together
- Theme applied to all components
- **🎉 MVP COMPLETE**
- Markdown viewer fully functional

### Phase 5 Success (Markdown Editor - Post-MVP)
### Phase 5 Success (Markdown Editor - MVP)
- Markdown editing mode functional
- Switch between preview/edit/split modes
- Save changes back to file
- Syntax highlighting works
- Split view with scroll sync

### MVP Success (Phases 1-4)
### MVP Success (Phases 1-5)
- Three co-equal panes (file browser, terminal, document viewer)
- Workspace tabs switch full context
- Zed terminal fully functional + URL clicking
Expand All @@ -861,15 +859,8 @@ All agents registered in: `.claude/agents/registry.yaml`

## 14. Post-MVP Enhancements

**Included in Phase 5 (Markdown Editor):**
- ✓ Markdown editing with syntax highlighting
- ✓ Preview/Edit/Split modes

**Future enhancements (not in current plan):**
- MCP integration layer
- Test visualization (structured test results)
- Agent execution visualization
- Live settings reload / hot-reload
- Image viewer (currently basic support only)
- Advanced image features (zoom, pan)
- Syntax highlighting in markdown code blocks (beyond basic)
Expand Down
15 changes: 9 additions & 6 deletions docs/REQUIREMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,8 @@ Existing tools force workflows into constrained patterns:

**Viewers**
- [ ] Markdown viewer - **PRIORITY** (preview/render mode)
- [ ] Image viewer (PNG, JPEG, GIF, SVG, TIFF)
- [ ] Image viewer (PNG, JPEG, GIF, TIFF)
- [ ] SVG viewer (required; defer if unsupported by chosen image stack)
- [ ] Automatic viewer selection by file type
- [ ] Zoom/pan for images

Expand All @@ -83,8 +84,9 @@ Existing tools force workflows into constrained patterns:
**Configuration**

*App-wide settings:*
- [ ] JSON-based settings file (`~/.config/terminalg/settings.json`)
- [ ] Platform-specific config directories
- [ ] JSON-based settings file (platform-specific config dir)
- [ ] Settings paths: macOS `~/Library/Application Support/terminalg/settings.json`, Linux `~/.config/terminalg/settings.json`, Windows `%APPDATA%\\terminalg\\settings.json`
- [ ] Versioned settings schema with migrations on load
- [ ] Theme system (dark/light built-in)
- [ ] Terminal settings (font, padding, scrollback)
- [ ] UI settings (default layout ratios, theme selection)
Expand All @@ -93,9 +95,10 @@ Existing tools force workflows into constrained patterns:
*Workspace configuration:*
- [ ] Separate config file per workspace
- [ ] Auto-save workspace state (open terminals, documents, pane sizes, visibility)
- [ ] Near-term: Store in `~/.config/terminalg/workspaces/<name>.json`
- [ ] Long-term: Support `.terminalg/<workspace>.json` in project repos
- [ ] Near-term: Store in platform config dir (macOS `~/Library/Application Support/terminalg/workspaces/<name>.json`, Linux `~/.config/terminalg/workspaces/<name>.json`, Windows `%APPDATA%\\terminalg\\workspaces\\<name>.json`)
- [ ] Workspace-local: Support `.terminalg/<workspace>.json` in project repos
- [ ] First-time workspace: Default to file browser + terminal (same root folder)
- [ ] App settings track all available workspaces and their config paths

### 4.2 Enhanced Features (Phase 4)

Expand Down Expand Up @@ -152,7 +155,7 @@ Existing tools force workflows into constrained patterns:
| Linux | ✓ Supported | glibc 2.31+, X11/Wayland |
| Windows | ✓ Supported | 10+, ConPTY support |

**All platforms supported from Phase 1** using Zed's cross-platform terminal implementation.
**Phase 1 validation on all platforms** (bootstrap app window). Full terminal support via Zed integration arrives in Phase 2.

**Primary development/testing:** macOS
**CI/Testing:** All platforms
Expand Down