From 979f5bd7677b8cf6ce1a8639752b4b7490ce218b Mon Sep 17 00:00:00 2001
From: kryptomrx <mrx.anonymousorg@gmail.com>
Date: Sat, 16 May 2026 23:21:21 +0200
Subject: [PATCH] docs: README and CHANGELOG for v0.1.0

---
 CHANGELOG.md |  26 ++++++++++++
 README.md    | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d9e4029
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to noz-cli are documented here.  
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-16
+
+### Added
+- Interactive REPL with topic-based navigation (`cd`, `ls`, `ls -la`, `tree`)
+- `cat` — print raw markdown of a note
+- `edit` — open note in terminal editor (nano/vim) or VS Code (`-c` flag)
+- `new` — create a new note from a template
+- `rm` — delete a note
+- `sync` — pull notes from server to local directory (parallel, hash-diffed)
+- `push` — push local markdown files to server
+- `search` — full-text search via Meilisearch
+- `config` — view and set editor preferences
+- `version` — show version and git hash
+- JSON note cache (`~/.cache/noz/notes.json`) for instant startup + background refresh
+- Cache timestamp displayed in startup stats line
+- Native AOT binary for macOS arm64 (~7.6 MB, no runtime required)
+- Tab completion for commands, slugs and folder segments
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..80d5cdf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# noz-cli
+
+A terminal REPL for [noz](https://github.com/kryptomrx/noz) — a self-hosted digital garden built with Next.js.
+
+Navigate, read, and edit your notes from the command line. Native AOT binary, no .NET runtime required.
+
+---
+
+## Install
+
+Download the latest binary from [Releases](../../releases) and place it on your PATH:
+
+```bash
+# macOS (Apple Silicon)
+curl -L https://github.com/kryptomrx/noz-cli/releases/latest/download/noz-osx-arm64 -o /usr/local/bin/noz
+chmod +x /usr/local/bin/noz
+```
+
+## Setup
+
+```bash
+noz init https://your-noz-instance.com your-api-token
+```
+
+This writes `~/.config/noz/config.json`.
+
+## Usage
+
+```
+noz
+```
+
+Starts the interactive REPL. Type `help` for a list of commands.
+
+### Navigation
+
+```
+~ » ls                  # list topics
+~ » cd psychologie      # enter a topic
+~/psychologie » ls -la  # detailed view with status, date, title
+~/psychologie » tree    # full hierarchy as a tree
+~/psychologie » cd ..   # go up
+```
+
+### Notes
+
+```
+~ » cat psychologie/flow-theorie   # print raw markdown
+~ » edit flow-theorie              # open in terminal editor
+~ » edit -c flow-theorie           # open in VS Code
+~ » new meine-neue-notiz           # create note from template
+~ » rm alte-notiz                  # delete a note
+```
+
+### Sync
+
+```
+~ » sync ~/vault                   # pull changed notes to local folder
+~ » sync ~/vault --all             # pull everything (ignore local hashes)
+~ » sync ~/vault --dry-run         # preview what would be downloaded
+~ » push ~/vault                   # push local .md files to server
+```
+
+### Other
+
+```
+~ » version     # show version + git hash
+~ » config      # show editor settings
+~ » config editor nano             # set terminal editor
+~ » config code-editor code        # set GUI editor
+~ » exit
+```
+
+## Configuration
+
+Editor preferences are stored in `~/.config/noz/config.json`:
+
+```json
+{
+  "server_url": "https://your-noz-instance.com",
+  "token": "...",
+  "editor": "nano",
+  "code_editor": "code"
+}
+```
+
+## Building from source
+
+Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) and `clang`.
+
+```bash
+git clone https://github.com/kryptomrx/noz-cli
+cd noz-cli
+
+# Run (no AOT)
+dotnet run --project NozCli
+
+# Native AOT binary (macOS arm64)
+dotnet publish NozCli/NozCli.csproj -r osx-arm64 -c Release
+```
+
+On macOS, AOT linking requires OpenSSL via Homebrew:
+
+```bash
+brew install openssl
+```
+
+## License
+
+[Polyform Noncommercial 1.0.0](LICENSE) — free for personal and non-commercial use.  
+For commercial licensing, contact [Bruno Deanoz](mailto:bruno.deanoz1@gmail.com).