# Wikied

`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.



## Run

From a published package:

```bash
npx wikied
npx wikied docs
```

From a local tarball on Windows (run from outside the project directory to avoid npm deduplication issues):

```powershell
cd $env:TEMP; npx --yes --package "C:\Projects\learning\site-editor\wikied-0.8.7.tgz" wikied "C:\path\to\your\docs"
```

Clone a repository before opening the editor:

```bash
wikied --git https://github.com/your-org/your-repo.git
```

## Documents

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

### Layout

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

### Theming

* **4 accent color themes**: Blue (default), Red, Purple, and Slate — selectable as color swatches in the Settings popover. Choice persists to localStorage.
* **Color scheme**: System / Light / Dark segmented control in Settings. Mantine applies preference immediately.
* Left navbar background is tinted with the active accent color (shade 0), with an accent-colored border separating the navbar header from the file tree (shade 2).
* Status bar, loading screen, and header brand mark all adapt to the active accent.

### File Tree

* Recursive file tree in the left navbar; Markdown files are enabled, non-Markdown files shown dimmed.
* Expand and collapse directories; active file highlighted.
* Orange filename and save icon on dirty (unsaved) files.
* New Markdown file button on directory hover.
* Rename action on the active file row.

### File Navigation

* Center filename pill in the header shows the active basename; click or press `Ctrl+P` to open an inline file picker.
* Picker shows the full folder tree when empty; collapses to a flat filtered list while typing.
* Orange dot beside the pill indicates the active file has unsaved changes.

### Editor Modes

* **Rich mode** (default): MDXEditor with toolbar for headings, emphasis, lists, links, images, tables, frontmatter, admonitions, and code blocks.
* **Preview mode**: GitHub-flavored Markdown rendering with Mermaid diagram support. Built-in style presets: Default, GitHub, Docs, Print, and Minimal.
* Toggle between modes via a floating pill button at the top-right of the editor canvas; the style selector opens from a chevron on the same pill.

### Dirty State and Saving

* Dirty indicators: orange dot beside the filename pill, orange badge count on the Save button, "Unsaved" badge in the status bar, orange filename in the file tree.
* **Save button** (floppy-disk icon): popover offers Save (current file) and Save all; shows dirty-count badge.
* **Autosave**: optional, enabled in Settings; triggers 750 ms after typing stops.
* `Ctrl+S` / `Cmd+S` saves the active file.
* Unsaved edits survive file switches via an in-memory content cache; switching back to a previously edited file restores those edits.

### Git Integration

* **Git button** (visible when the workspace is a git repository): badge shows changed-file count; updates on every save and every 10 seconds.
* Popover offers: **Commit** (opens message modal, runs `git add -A && git commit`), **Push**, and **Pull**. Errors and results shown inline.
* **Clone-on-empty-root modal**: when the workspace is empty, the browser prompts to clone a repository URL or start empty.

### Panels

* **Outline panel**: lists headings from the active document; supports heading search; opens as a right-side Drawer or pins to the Aside.
* **Recent panel**: lists the 10 most recently opened files; click to reopen; opens as a Drawer or pins to the Aside.
* Only one panel can be pinned at a time.

### Navigation and Help

* **Settings popover**: accent color swatches, color scheme selector (System / Light / Dark), autosave toggle.
* **Help modal**: in-app user guide covering all major features and keyboard shortcuts.
* **About modal**: app description and version.
* **Status bar**: active file path, Saved/Unsaved badge, current mode, Markdown, UTF-8, LF, Local only.

### Server Features

* Path safety on all filesystem operations (traversal, symlink escape, root-bounds checks).
* Revision conflict detection: save is rejected if the file changed on disk since it was loaded.
* UTF-16 LE BOM decoding: files saved by Windows tools render correctly; always written back as UTF-8.
* REST API: health, file tree, file content read/write, file create, rename, asset copy, git status/commit/push/pull, settings load/save.

## 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.
