# Wikied Project Documentation — v0.9.1

`wikied` is a local Markdown editor for project documentation. It starts from a Node CLI, serves a localhost-only Express app, and edits Markdown files under the selected workspace root.

The current app is implemented and packaged as `wikied@0.9.1`. The original approved product design remains at `docs/superpowers/specs/2026-05-17-wikied-design.md`; this directory documents the implemented behavior.

## Screenshots

![Wikied editor workspace — Rich mode](images/workspace-source.png)

![Wikied preview mode with Mermaid support](images/preview-mermaid.png)

![Wikied unsaved document state](images/dirty-document.png)

## Documents

* [Requirements](requirements.md): implemented product goals, current scope, known gaps, and acceptance criteria.
* [Architecture](architecture.md): CLI, server, client, API, settings, path safety, and data flow.
* [Technical Specification](tech-spec.md): package layout, REST API, revision model, Markdown support, and test strategy.
* [Design](design.md): current UI layout, editor modes, file tree behavior, screenshots, and accessibility notes.
* [How To Run Wikied](how-to/run.md): user-facing CLI and browser workflow.
* [How To Develop](how-to/develop.md): contributor setup and development commands.
* [How To Package And Run Locally](how-to/package-local.md): clean local build, `npm pack`, and tarball execution.
* [How To Test](how-to/test.md): unit, client, server, e2e, lint, and screenshot checks.
* [How To Release](how-to/release.md): pre-release validation and publish checklist.
* [Changelog](changelog.md): release notes and notable user-facing changes.

## Current Feature Set

### CLI and Server

* CLI startup through `wikied`, `npx --package <tarball> wikied`, or `node dist/cli/index.js`.
* Optional root path argument; defaults to the current directory.
* `--git <url>` flag clones a repository into an empty directory before starting the server.
* Localhost-only Express server bound to `127.0.0.1`.
* Bundled React app served from `dist/client`.
* Server requires Node.js 20 or later.

### Application Layout

* Mantine AppShell with a 48 px fixed header, left file-tree navbar (260 px, collapsible), conditionally rendered right aside (300 px), full-width editor canvas, and a 24 px sticky status bar at the bottom.
* Left file-tree panel toggled by a hamburger icon in the top-left; open/closed state persisted to localStorage across sessions.
* Right aside panel persists its pinned-panel and open/closed state to localStorage.

### Theming and Appearance

* **4 accent color themes** selectable in Settings:
  * **Blue** (default) — #1f8fbe
  * **Red** — #f21616
  * **Purple** — #504c97
  * **Slate** — #555455
* Accent swatches shown as circular color chips in the Settings popover; selection persists to localStorage and rebuilds the Mantine theme immediately without a page reload.
* **Color scheme**: System / Light / Dark segmented control in Settings; preference applied immediately via Mantine.
* Left navbar tinted with the active accent (shade 0 background, shade 2 border on the navbar header divider).
* Status bar, loading screen logo, version badge, and header brand mark all use the active accent color.

### File Tree (Left Navbar)

* Recursive file tree rendered in the left navbar; Markdown files are selectable, non-Markdown files shown dimmed.
* Directories expand and collapse; state is preserved during the session.
* Active file row is highlighted; shows Rename and Save icon buttons on hover.
* Dirty (unsaved) files shown with an orange filename and a save icon.
* New Markdown file button appears on directory hover.
* Recent files section at the top of the tree (collapsible).

### File Navigation

* Center filename pill in the header shows the active file's basename, or "Open a file…" when nothing is open.
* Click the pill or press `Ctrl+P` to open an inline file search combobox:
  * Shows the full folder tree when no query is typed.
  * Collapses to a flat filtered list while typing.
  * Markdown files are selectable; non-Markdown files shown dimmed.
  * `Escape` closes the picker without selection.
* Orange dot beside the pill indicates the active file has unsaved changes.

### Editor Modes

* **Rich mode** (default): MDXEditor with toolbar controls for headings, bold, italic, underline, lists, links, images, tables, frontmatter, admonitions, code inline, and code blocks.
* **Preview mode**: GitHub-flavored Markdown rendering with Mermaid diagram support. Relative Markdown links open the target in the same editor; dirty files prompt to save first.
* Built-in Preview style presets: Default, GitHub, Docs, Print, and Minimal.
* Mode toggle: a floating pill button at the top-right of the editor canvas switches between Rich and Preview. A chevron on the pill opens the style selector when in Preview mode.

### Dirty State and Saving

* Dirty state is shown in four places simultaneously:
  * Orange dot to the right of the filename pill.
  * Orange badge count on the Save button in the header.
  * "Unsaved" badge (green "Saved" when clean) in the status bar.
  * Orange filename and save icon on the active row in the file tree.
* **Save button** (floppy-disk icon in the header): badge shows dirty-file count; popover offers **Save** (active file) and **Save all**.
* `Ctrl+S` / `Cmd+S` saves the active file.
* **Autosave**: optional; enabled in Settings; triggers 750 ms after typing stops.
* Unsaved edits are cached in memory when switching files; switching back restores the edits and keeps the file dirty.

### Git Integration

* **Git button** (branch icon, visible only when the workspace is a git repository):
  * Badge shows the number of changed files; updates on every save and every 10 seconds.
  * Popover offers: **Commit** (opens a modal for the message, then runs `git add -A && git commit`), **Push**, and **Pull**.
  * Errors and success messages shown inline in the popover.
* **Clone-on-empty-root modal**: when the workspace is empty, the browser shows a modal to clone a repository by URL or start with an empty workspace. The `--git <url>` CLI flag is the non-interactive alternative.

### Panels

* **Outline panel**: lists headings extracted from the active Markdown document; supports search/filter; opens as a 300 px right-side Drawer or can be pinned to the persistent Aside column.
* **Recent panel**: lists the 10 most recently opened files; click any entry to open it; opens as a Drawer or pins to the Aside.
* Only one panel can be pinned to the Aside at a time; pinned state persists to localStorage.

### Header Action Icons

| Icon         | Action                                                                             |
| ------------ | ---------------------------------------------------------------------------------- |
| Save         | Popover with Save and Save all; dirty-count badge                                  |
| Export       | Dropdown (Preview mode only): Export as PDF, DOC, or HTML; hidden in Rich mode     |
| Git          | Popover with Commit, Push, Pull; changed-file-count badge; only shown in git repos |
| Outline      | Opens the Outline drawer or unpin it from the aside                                |
| Recent       | Opens the Recent files drawer or unpins it from the aside                          |
| Settings     | Popover: accent swatches, color scheme selector, autosave toggle                   |
| Help & About | Opens the in-app user guide and About information                                  |

### Help and About

* **Help modal**: in-app user guide covering file navigation, editing, saving, Preview mode, the Outline and Recent panels, Git operations, Settings, and keyboard shortcuts.
* **About modal**: app name, description, and current version number.

### Status Bar

24 px sticky bar at the bottom of the window; always visible during scroll:

* Active file path (full path, with tooltip on overflow).
* Saved/Unsaved badge (green/yellow).
* Current editor mode (Rich / Preview).
* Static metadata: Markdown, UTF-8, LF, Local only.

### Server and Safety

* All filesystem operations validated on the server: path-traversal checks, symlink-escape prevention, root-bounds enforcement.
* **Revision conflict detection**: save is rejected if the file changed on disk since it was loaded; the client receives a structured error.
* **UTF-16 LE BOM decoding**: files saved by Windows tools render correctly; always written back as UTF-8.

### REST API Surface

| Method | Path                 | Purpose                                    |
| ------ | -------------------- | ------------------------------------------ |
| GET    | `/api/health`        | App status, root info, isEmpty, isGitRepo  |
| POST   | `/api/clone`         | Clone a git repo into an empty root        |
| GET    | `/api/tree`          | Recursive file tree with editability flags |
| GET    | `/api/files/content` | Read a Markdown file                       |
| PUT    | `/api/files/content` | Save with revision conflict detection      |
| POST   | `/api/files`         | Create a new Markdown file                 |
| PATCH  | `/api/files/rename`  | Rename a file                              |
| POST   | `/api/assets`        | Copy an asset with a relative path         |
| GET    | `/api/git/status`    | Changed-file count                         |
| POST   | `/api/git/commit`    | Stage all and commit                       |
| POST   | `/api/git/push`      | Push to remote                             |
| POST   | `/api/git/pull`      | Pull from remote                           |
| GET    | `/api/settings`      | Load user settings                         |
| PUT    | `/api/settings`      | Save user settings                         |

### Mermaid Diagram Builder

* **Toolbar** — compact row above the full-width canvas: title input, Add Participant/Actor/Message/Block icons, Edit Elements, Reorder, View/Edit Code, Export, and Autonumber toggle.
* **Add modals** — separate modals for participant (covers actor via type selector), message (with block assignment), and block.
* **Edit Elements modal** — searchable flat list of all participants and steps; pencil reopens the relevant form pre-populated; delete is immediate for participants/messages, inline-confirm for blocks.
* **Reorder modal** — two drag zones using @dnd-kit: participants at top, full nested step tree below (supports root, inside-block, and inside-branch drag).
* **View/Edit Code modal** — shows live serialised Mermaid in an editable textarea; Apply parses it back into the diagram model; Cancel discards changes.
* **Export menu** — single dropdown: Download SVG, Download PNG, Download `.mmd`, Copy Mermaid code. Disabled until a diagram renders. Shared between toolbar and fullscreen preview modal.
* **Fullscreen preview** — hover over any rendered Mermaid diagram in Preview mode to reveal a "Full screen" button; opens a full-viewport modal with pan/zoom and the Export menu.

## Known Gaps

* Save conflict responses are not yet routed into the `ConflictView` component.
* The asset-copy API and rich editor image controls exist but are not connected end-to-end.
* The right aside is fixed at 300 px; drag-to-resize is not yet implemented.
* No project-wide full-text search, broken-link report, or multi-document tab management.