# Requirements

## Purpose

`wikied` helps docs maintainers edit Markdown files inside a local project directory without installing a documentation platform. A user can start one localhost-only command, open a browser editor, inspect the project structure, edit Markdown, and save changes back to disk.

## Primary User

The primary user is a docs or project maintainer working in a repository. They care about readable editing, exact Markdown control when needed, predictable file operations, and safety around filesystem writes.

## Product Goals

* Start from the package binary with `wikied` or from a local tarball with `npx --package`.
* Open the current directory by default and accept an optional root path.
* Support `--git <url>` to clone a repository into an empty directory before starting.
* Serve a prebuilt React app from a localhost-only Express server.
* Show files and directories recursively under the opened root.
* Enable editing for `.md` and `.markdown` files.
* Show non-Markdown files for context while keeping them disabled.
* Provide Rich and Preview modes.
* Render GitHub-flavored Markdown and Mermaid diagrams in Preview mode.
* Track dirty state across multiple files and support explicit saves.
* Support Save all to commit every dirty file in a single action.
* Support optional autosave from user settings.
* Open relative document links from Preview mode in the same editor.
* Store settings outside the opened project directory.
* Validate every filesystem path on the server.
* Provide git operations (commit, push, pull) when the workspace is a git repository.

## Current Scope

The implemented app includes:

* CLI startup and localhost server startup.
* `--git <url>` flag for pre-flight repository clone into an empty directory.
* Clone-on-empty-root modal in the browser UI.
* User-level settings with defaults for browser auto-open, autosave, asset folder, and recent files.
* Mantine `AppShell` layout with top bar, right aside, and full-width editor main area.
* Center filename pill with inline filterable file picker; `Ctrl+P` also opens the picker.
* Orange dirty-state dot beside the filename pill.
* Recursive file tree accessible from the filename pill combobox.
* Recent files panel (Drawer and pinnable Aside).
* Outline panel (Drawer and pinnable Aside) with heading search.
* Single active Markdown document.
* Rich editing through MDXEditor.
* Rendered Preview mode with built-in style presets (Default, GitHub, Docs, Print, Minimal).
* Mermaid rendering for fenced `mermaid` code blocks.
* Floating preview pill for mode switching; chevron popover for style selection.
* Settings popover with theme selector (System / Light / Dark) and autosave toggle.
* About modal.
* Visible app version badge in the top bar.
* Save button with dirty-count badge; popover offers Save (active file) and Save all.
* Multi-file dirty state: unsaved edits are preserved in a content cache when switching files; Save all saves every cached dirty file.
* Git button with changed-files badge; popover offers Commit (with message modal), Push, and Pull. Only shown when the workspace is a git repository.
* Dirty-state indicators: orange dot beside the filename pill, orange count badge on the Save button, Unsaved/Saved badge in the status bar, and orange filename in the file tree.
* Status bar with file path, dirty badge, mode, and static metadata.
* Manual save through keyboard shortcut (`Ctrl+S` / `Cmd+S`).
* Optional autosave.
* Server-side revision conflict detection.
* Server-side local asset copy endpoint.
* Safe root-relative path handling.
* UTF-16 LE BOM file decoding.
* Left file-tree sidebar toggled by a hamburger icon; open/closed state persisted to localStorage.
* Accent color themes (Blue, Red, Purple, Slate) selectable as swatches in the Settings popover; navbar tint and status bar adapt to the active accent.
* Visual diagram builder (`dex` package) — form-driven UI for sequence, flowchart, ER, and org chart diagrams with live pan/zoom canvas, modal element management (Add, Edit, Reorder), raw Mermaid code editing with Apply-back, export (SVG, PNG, `.mmd`, clipboard copy), and fullscreen preview modal.
* **Diagrams** header tab for standalone diagram editing.
* Insert Diagram button in the Rich editor toolbar: opens the diagram builder in-place and appends a ` ```mermaid ``` ` fenced block on confirm.
* Gliffy-to-Mermaid converter (`src/shared/gliffy/`) shared by browser and CLI; supports flowchart, sequence, ER, and org chart; lossy by design.
* Import Gliffy modal accessible from both the editor toolbar (Gliffy button) and the Dex toolbar; includes file upload and paste-JSON tabs with live preview.
* `wikied convert --input <file> --output <file>` CLI subcommand for batch Gliffy-to-Markdown conversion; exits 1 on error, 0 with stderr warnings for unrecognised shapes.

## Known Gaps

The following are not fully shipped in the app shell yet:

* Save conflict responses are not yet connected to the visible conflict resolution view.
* Local image copy is available on the server, but the rich editor image control is not yet wired to the custom asset-copy API.
* The right aside column is fixed at 300 px; drag-to-resize is not yet implemented.
* There is no file creation, rename, or deletion from the UI in this version (server APIs remain).
* There is no full-text search or broken-link checking.
* There is no multi-document tab set.

## Non-Goals For This Version

* LAN or remote access.
* Authentication.
* Multi-user collaboration.
* Project-local `.wikiedrc` configuration.
* First-class MDX project semantics.
* Publishing or hosting documentation.

## User Stories

* As a maintainer, I can run `wikied` or `npx --package <tarball> wikied` and edit Markdown files in the selected workspace.
* As a maintainer, I can run `wikied docs` to limit editing to a documentation folder.
* As a maintainer, I can run `wikied --git <url>` to clone a repository and open it immediately.
* As a maintainer, I can clone a repository from the browser UI when wikied starts in an empty directory.
* As a maintainer, I can use a rich editor for normal writing.
* As a maintainer, I can preview Markdown, including Mermaid diagrams.
* As a maintainer, I can see non-Markdown files in the picker so the project shape remains understandable.
* As a maintainer, I can open any Markdown file quickly using the filename pill or `Ctrl+P`.
* As a maintainer, I can identify unsaved work from the orange dot beside the pill, the Save badge, and the status bar.
* As a maintainer, I can save all dirty files at once without saving each file individually.
* As a maintainer, I can switch between files without losing unsaved edits; switching back restores my changes.
* As a maintainer, I can commit, push, and pull changes directly from the editor header.
* As a maintainer, I can open a relative Markdown link from Preview mode without leaving the editor.
* As a maintainer, I can rely on server-side path checks to prevent writes outside the opened root.
* As a maintainer, I can open a persistent file-tree sidebar to browse my workspace without using the picker.
* As a maintainer, I can choose an accent color theme so the UI matches my preference.
* As a maintainer, I can build a Mermaid diagram visually in the diagram builder and confirm it into my document.
* As a maintainer, I can export a diagram as SVG, PNG, or raw Mermaid from the diagram builder.
* As a maintainer, I can import a Gliffy file from the editor toolbar or diagram builder and see a converted Mermaid diagram inserted into my document.
* As a maintainer, I can run `wikied convert` on the command line to convert a Gliffy file to Markdown without starting the server.

## Acceptance Criteria

* `wikied` starts a localhost-only server for the current working directory.
* `wikied <path>` starts a localhost-only server for the provided directory.
* `wikied --git <url>` clones into the target directory before starting; fails if the directory is not empty.
* `--no-open` prevents browser launch.
* `--port <number>` binds to the requested port.
* When wikied starts in an empty directory, the browser shows a clone-or-start-empty modal.
* The file picker lists Markdown and non-Markdown files, but only `.md` and `.markdown` files are selectable.
* Rich and Preview modes are available for an active Markdown file.
* Preview mode renders Mermaid diagrams.
* Preview mode can switch between built-in style presets from the floating pill chevron.
* An orange dot appears beside the filename pill for dirty documents.
* The Save button badge shows the number of dirty files.
* Save all saves every dirty file, including files whose edits were cached during a file switch.
* The Git button and badge are only visible when the workspace is a git repository.
* Commit requires a non-empty message; errors appear inline in the modal.
* The Outline panel can filter headings by search text.
* Manual save works through the keyboard shortcut (`Ctrl+S` / `Cmd+S`).
* Autosave runs when enabled in settings.
* Relative Preview links resolve from the active document path and open in the editor.
* Save requests compare the client revision with the current disk revision.
* UTF-16 LE encoded Markdown files are decoded and displayed correctly.
* The left file-tree sidebar can be toggled with the hamburger icon; its state persists across reloads.
* The Settings popover shows four accent color swatches; selecting one updates the navbar and status bar immediately.
* The Diagrams tab opens the diagram builder; the builder renders a live Mermaid preview and offers export options.
* The Insert Diagram toolbar button opens the diagram builder in-place and appends a Mermaid fenced block to the document on confirm.
* The Import Gliffy modal (editor and Dex toolbar) accepts a `.gliffy` file or pasted JSON and shows a live Mermaid preview before insertion.
* `wikied convert --input <file> --output <file>` writes a Markdown file with a Mermaid code block; exits 1 on fatal error; prints shape warnings to stderr with exit code 0.
