@nemus-cli/nemus 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-08-24
+
+### Security
+
+- **Fixed a path-traversal vulnerability in the MCP server.** The MCP tool
+  handlers built filesystem paths (`path.join(WORKSPACES_DIR, workspace)`)
+  directly from the caller-supplied `workspace` argument with no validation, so
+  an MCP client could pass a value like `../../etc` to read, write, delete
+  (`delete-workspace`), or run commands (`run-command`) **outside** the
+  workspaces directory. All handlers now resolve workspace paths through a new
+  `safeWorkspacePath()` choke point that enforces an allowlist
+  (`^[A-Za-z0-9_-]+$`) **and** verifies the resolved path stays inside
+  `WORKSPACES_DIR`. The MCP input schemas additionally reject traversal
+  characters at the boundary (defense in depth). The archive/unarchive metadata
+  paths are hardened the same way.
+
+## [0.2.0] - 2026-08-24
+
+### Added
+
+- **Investigate-first workspaces.** When `nemus -- "<prompt>"` doesn't name
+  concrete repos but asks the agent to figure out which repos are relevant (from
+  a trace, stack trace, or log search), Nemus now creates an **empty** workspace
+  and seeds the in-session agent with a discover-then-add workflow: it
+  investigates, maps services to repos (MCP `search-repos` when available, else
+  the `gh` CLI, honouring a configured org), adds them with `nemus update`, and
+  only then reads the code.
+- `nemus create --allow-empty` creates a zero-repo workspace that still writes
+  the agent context + `.mcp.json`, so the agent lands with the tools to discover
+  and add repos.
+
+### Changed
+
+- `nemus update` (CLI and MCP) regenerates the agent context after a successful
+  add, so a freshly-populated workspace stops reporting "0 repositories."
+- Context regeneration now **preserves operator-authored `## Notes`** instead of
+  overwriting them.
+- Shell integration probes installed agents (claude → pi → opencode → codex →
+  gemini) when `primaryAgent=auto`, instead of assuming `claude`.
+
+### Fixed
+
+- Extraction now coerces malformed model output (wrong field types) to safe
+  empties instead of throwing.
+- Corrected internal command references that still invoked the pre-rename `w`
+  binary; they now use `nemus`.
+
+## [0.1.0] - 2026-08-24
+
+Initial open-source release of **Nemus**.
+
+### Added
+
+- Multi-repository **workspaces**: create, list, update, delete, and jump to
+  folders of related Git repositories.
+- Bulk operations across every repo in a workspace: `status`, `sync`, `diff`,
+  `run`, and `doctor` (health checks + score).
+- **Branch operations** (switch/create/merge/rebase) across all repos.
+- **Suites** — reusable repo collections with optional post-clone hooks, plus
+  export/import.
+- **Snapshots** — capture and restore exact workspace state.
+- **Cache** management for the GitHub repo list.
+- **Dependency analysis** and **doc generation** across a workspace.
+- **AI-agent integration** for Claude Code, pi, OpenCode, Codex, and Gemini:
+  generated context files, skills installation, hooks (where supported), and an
+  **MCP server** (`nemus-mcp`).
+- Provider-agnostic by design — works with whatever model provider your agent
+  supports (Anthropic, OpenAI, Google, or Amazon Bedrock).
+- Natural-language front door: `nemus -- "<prompt>"`.
+- Interactive TUI and a multi-agent dashboard.
+- Automatic retries with backoff on flaky network operations.
+- Optional shell integration (auto-cd on create + quick-navigate helper).
+
+[Unreleased]: https://github.com/me-public/nemus/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/me-public/nemus/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/me-public/nemus/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/me-public/nemus/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nemus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+<p align="center">
+  <img src="assets/logo-wordmark.svg" alt="Nemus" width="320" />
+</p>
+
+<p align="center">
+  <b>Multi-repo workspaces for the AI-agent era.</b><br/>
+  Create, sync, and operate across dozens of Git repositories with a single command —
+  and wire them up to your favorite coding agent.
+</p>
+
+<p align="center">
+  <a href="https://github.com/me-public/nemus/actions/workflows/ci.yml"><img src="https://github.com/me-public/nemus/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@nemus-cli/nemus"><img src="https://img.shields.io/npm/v/@nemus-cli/nemus.svg" alt="npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22" />
+</p>
+
+---
+
+## The name
+
+**Nemus** (_NEH-mus_) is Latin for a **grove** — a small wood of trees sharing
+soil and roots. It's a fitting picture of what the tool manages: a cluster of
+repositories, each its own tree, growing together in one workspace. It also nods
+to the branch-and-commit shape of Git itself.
+
+## Why Nemus?
+
+Modern products span many repositories. Nemus keeps a **workspace** — a named folder
+of related repos — in sync and lets you act across all of them at once: clone, pull,
+branch, run commands, check status, and diff. Then it connects that workspace to a
+coding agent (Claude Code, pi, OpenCode, Codex, Gemini) with generated context files,
+skills, and an MCP server, so "work on the payments stack" becomes a single prompt.
+
+- 🌳 **Workspaces** — group repos, clone them all, jump in.
+- 🔁 **Operate in bulk** — status, sync, diff, run, branch across every repo.
+- 📦 **Suites & snapshots** — save reusable repo collections and exact states.
+- 🤖 **Agent-native** — first-class integration with multiple coding agents.
+- 🩺 **Healthy by default** — health checks, dependency analysis, retries.
+
+## A full clone per workspace — on purpose
+
+This is the core design decision, so it's worth being explicit: **every workspace
+gets its own independent, full `git clone` of each repo.** Two workspaces that both
+contain `api` hold two separate clones — each with its own `.git`, index, stash,
+hooks, config, branches, and build artifacts.
+
+A reasonable question is *"why not `git worktree`?"* Worktrees attach multiple
+working directories to **one shared repository**, which is great for flipping
+between branches of a **single** repo. But Nemus is built for **many repos worked
+on in parallel — often by AI agents — at the same time**, and there full clones win:
+
+| | **Nemus: clone per workspace** | **`git worktree`** |
+|---|---|---|
+| **Scope** | Spans **many repos** per workspace uniformly | A **single-repo** feature (`git worktree add` lives inside one repo) |
+| **Isolation** | Total: separate `.git`, index, stash, config, **hooks**, and build outputs (`node_modules/`, `target/`, `dist/`) | Partial: worktrees **share** the object store, config, and hooks |
+| **Same branch, twice** | ✅ Two workspaces can both sit on `main` (e.g. stable vs. experiment) | ❌ Git refuses to check out the same branch in two worktrees |
+| **Parallel agents** | Safe: one agent's rebase/branch-switch/`gc`/dirty tree can't touch another's | Risky: aggressive concurrent ops share one object DB + refs |
+| **Per-workspace remotes/creds** | ✅ Each clone can point at a different fork/remote | ❌ Remotes are shared |
+| **Disposable** | It's just a directory — `rm -rf` is safe | Needs `git worktree remove`; a stale/broken worktree can corrupt the parent's list |
+| **Tooling** | Every dir is a normal repo — IDEs, scripts, and git tools "just work" | Some tools mishandle the `.git`-file pointer / shared hooks |
+
+**The honest trade-off:** full clones use more disk and take longer to set up than a
+worktree that shares the object store. Nemus leans into that on purpose and softens
+it — clones run **in parallel**, retry on flaky networks, and the repo list is
+cached. For juggling many repos across several workspaces (and several agents), the
+bulletproof isolation is worth the extra gigabytes. If you're switching branches
+within one repo, plain `git worktree` is still the right tool — Nemus solves the
+different problem of *many* repos in *many* independent workspaces.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @nemus-cli/nemus
+
+# One-time setup (choose your GitHub org, agent, clone protocol…)
+nemus configure
+
+# Create your first workspace (interactive repo picker with fuzzy search)
+nemus create
+
+# Or let an agent do it — describe what you need in plain English
+nemus -- create a workspace with all payments-related repos
+```
+
+After creation you're dropped into the workspace directory with all repos cloned.
+
+> `nemus` and the shorter `nem` are equivalent. Use whichever you like.
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g @nemus-cli/nemus
+```
+
+The postinstall step sets up optional shell integration (auto-cd into new
+workspaces + a quick-navigate helper).
+
+### From source
+
+```bash
+git clone https://github.com/me-public/nemus.git
+cd nemus
+npm install
+npm run build
+npm link   # makes `nemus` / `nem` available on your PATH
+```
+
+### Prerequisites
+
+- **Node.js 22+**
+- Git
+- [GitHub CLI](https://cli.github.com/) (`gh`), authenticated via `gh auth login`
+- SSH keys configured for GitHub (recommended; HTTPS also supported)
+
+## Connecting AI agents
+
+Nemus is agent-agnostic. It detects installed agent CLIs and, for each active
+agent, writes the right context file, installs skills, and (where supported)
+registers its MCP server and hooks.
+
+| Agent | CLI | Context file | MCP | Notes |
+|-------|-----|--------------|-----|-------|
+| **Claude Code** | `claude` | `CLAUDE.md` | ✅ | Hooks + status line supported |
+| **pi** | `pi` | `AGENTS.md` | — | |
+| **OpenCode** | `opencode` | `AGENTS.md` | ✅ | Reads `~/.claude/skills` natively |
+| **Codex** (OpenAI) | `codex` | `AGENTS.md` | ✅ | Reads `~/.codex/config.toml` |
+| **Gemini** (Google) | `gemini` | `GEMINI.md` | ✅ | |
+
+Choose your agent(s) during `nemus configure`, or set them any time:
+
+```bash
+nemus configure          # interactive
+# aiAgent:      claude | pi | opencode | codex | gemini | both | auto
+# primaryAgent: claude | pi | opencode | codex | gemini | auto
+```
+
+- `auto` detects installed CLIs and picks sensibly.
+- `both` means **every** installed agent (context files + skills written for all).
+
+### Model providers
+
+The agent CLIs own model/provider auth, so Nemus works with **any provider your
+agent supports** — Anthropic, OpenAI, Google, or **Amazon Bedrock** — with no extra
+configuration in Nemus. For example, Claude Code and pi both run against Bedrock via
+their own environment (`CLAUDE_CODE_USE_BEDROCK=1`, or pi's `amazon-bedrock`
+provider); Codex and Gemini authenticate to OpenAI and Google respectively. Point
+your agent at whichever provider you like — Nemus just drives the agent.
+
+## Usage
+
+Every command has a short alias (shown in parentheses).
+
+### Create & manage workspaces
+
+```bash
+nemus create           # (c) interactive create
+nemus list             # (l) list workspaces
+nemus update           # (u) add repos to a workspace
+nemus delete           # (del) delete a workspace
+nemus go [name]        # jump to a workspace directory
+```
+
+### Operate across all repos
+
+```bash
+nemus status my-workspace     # (st) git status for every repo
+nemus sync my-workspace       # (s) git pull every repo (auto-retries on flaky network)
+nemus diff my-workspace       # (d) combined diff summary  (--full for raw diffs)
+nemus run my-workspace "npm install"   # (r) run a command in every repo
+nemus doctor my-workspace     # (doc) health checks + score
+```
+
+```
+Repo             Branch       Status        Ahead/Behind   Modified
+─────────────────────────────────────────────────────────────────────
+api              main         ✓ Clean       Up to date     -
+web              feature/x    ⚠ 2 modified  ↑1             2 files
+shared-lib       main         ✓ Clean       ↓3             -
+```
+
+### Suites (reusable repo collections)
+
+```bash
+nemus suite create            # (sc) save a set of repos (+ optional post-clone hooks)
+nemus suite list              # (sls)
+nemus suite use               # (fs) create a workspace from a suite
+nemus suite export my-suite -o my-suite.json
+nemus suite import my-suite.json
+```
+
+### Branches & snapshots
+
+```bash
+nemus branch switch           # (sb) switch every repo to a branch
+nemus branch create ws feature/new-thing   # (bc)
+nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
+nemus snapshot restore <id>   # (sr)
+```
+
+### AI assistant
+
+```bash
+nemus -- create a workspace for the payments team
+nemus -- list my workspaces and show their status
+
+# Investigate-first: create an EMPTY workspace and let the agent discover the repos
+nemus -- search the logs for the OCR 500s, find the services in the trace, and open those repos
+```
+
+**Investigate-first workspaces:** when your prompt doesn't name concrete repos but
+asks the agent to *figure out* which repos are relevant (from a trace, a stack
+trace, or a log search), Nemus creates an **empty** workspace and hands the agent a
+discover-then-add workflow: it investigates, maps the services it finds to repos
+(fuzzy `search-repos`, or the `gh` CLI), adds them with `nemus update`, and only
+then digs into the code.
+
+Nemus exposes an **MCP server** (`nemus-mcp`) so MCP-capable agents can search
+repos, create/update workspaces, check status, and more directly from a prompt.
+
+Run `nemus --help` for the full command reference.
+
+## Configuration
+
+`nemus configure` writes `~/.workspace-manager-cache/config.json`. Environment
+variables override it:
+
+```bash
+export WORKSPACE_MANAGER_DIR="$HOME/my-workspaces"      # default: ~/workspaces
+export WORKSPACE_MANAGER_CACHE_DIR="$HOME/.cache/nemus" # default: ~/.workspace-manager-cache
+```
+
+Key settings: `githubOrg` (which org's repos to list — leave empty to list your
+own), `cloneProtocol` (`ssh`|`https`), `aiAgent`, `primaryAgent`, `installMcp`.
+
+## Workspace layout
+
+```
+~/workspaces/
+└── my-workspace/
+    ├── .workspace-meta.json    # repos, timestamps, health
+    ├── AGENTS.md / CLAUDE.md    # generated agent context
+    ├── api/                     # cloned repos
+    ├── web/
+    └── shared-lib/
+```
+
+## Development
+
+```bash
+npm run build        # compile TypeScript
+npm test             # run the test suite (vitest)
+npm run typecheck    # tsc --noEmit
+npm link             # use your local build globally
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and
+[docs/architecture.md](docs/architecture.md) for a tour of the codebase.
+
+## Releasing
+
+Releases are automated and gated by a manual approval. Bump the version, merge to
+`main`, and approve the deployment — see [docs/releasing.md](docs/releasing.md).
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and our
+[Code of Conduct](CODE_OF_CONDUCT.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Nemus contributors

package/assets/README.md

@@ -0,0 +1,53 @@
+# Nemus brand assets
+
+Original artwork for **Nemus** (Latin for *grove*). The mark is an **organic
+sapling that doubles as a git commit graph** — a trunk branching into commit-dot
+"buds," with one highlighted *active* node. It reads at once as a young *tree* (the
+grove), a *branch/commit graph*, and repos growing from a shared root. The square
+app **icon** is a bold negative-space tree with a `>_` terminal prompt carved into
+the canopy, so it stays legible down to favicon sizes. Hero imagery uses a
+terminal-window motif in a GitHub-dark palette for a developer-native feel.
+
+## Files
+
+| File | Use |
+|------|-----|
+| `logo.svg` / `logo-256.png` / `logo-512.png` | The logo mark. Transparent background — use on light or dark surfaces. |
+| `logo-wordmark.svg` | Mark + "Nemus" wordmark. Use in README headers and docs. |
+| `icon.svg` / `icon-256.png` | Square app icon (rounded-rect green background). Use for avatars/app icons. |
+| `favicon-32.png` / `favicon-64.png` | Favicons derived from the icon. |
+| `banner.svg` / `banner.png` | 1280×640 social/repo banner (GitHub "social preview"). |
+
+## Color palette
+
+GitHub-familiar greens on a dark canvas.
+
+| Token | Hex | Use |
+|-------|-----|-----|
+| Green (primary) | `#3FB950` | Primary brand green (nodes) |
+| Green (deep) | `#238636` / `#2EA043` | Edges, gradients, wordmark on light/dark |
+| Green (bright) | `#56D364` | Node highlights |
+| Mint | `#7EE2A8` | Accent / subtitle text on dark |
+| Canvas | `#0D1117` / `#0A0E14` | Dark backgrounds (banner, icon) |
+| Panel | `#161B22` | Terminal window / tile surface |
+| Border | `#30363D` | Hairline borders |
+| Text | `#E6EDF3` | Primary text on dark |
+| Muted | `#7D8590` / `#8B949E` | Secondary text |
+
+Terminal traffic-light dots: `#FF5F56` `#FFBD2E` `#27C93F`.
+
+## Regenerating the PNGs
+
+The PNGs are rasterized from the SVGs with [`rsvg-convert`](https://gitlab.gnome.org/GNOME/librsvg)
+(or ImageMagick's `magick`):
+
+```bash
+rsvg-convert -w 512 -h 512 logo.svg  -o logo-512.png
+rsvg-convert -w 256 -h 256 logo.svg  -o logo-256.png
+rsvg-convert -w 256 -h 256 icon.svg  -o icon-256.png
+rsvg-convert -w 64  -h 64  icon.svg  -o favicon-64.png
+rsvg-convert -w 32  -h 32  icon.svg  -o favicon-32.png
+rsvg-convert -w 1280 -h 640 banner.svg -o banner.png
+```
+
+All artwork is original and released under the project's [MIT license](../LICENSE).

package/assets/banner.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640" role="img" aria-label="Nemus — multi-repo workspaces for the AI-agent era">
+  <title>Nemus</title>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0D1117"/>
+      <stop offset="1" stop-color="#0A0E14"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.72" cy="0.32" r="0.55">
+      <stop offset="0" stop-color="#2EA043" stop-opacity="0.32"/>
+      <stop offset="1" stop-color="#2EA043" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="edge" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#1F7A34"/>
+    </linearGradient>
+    <radialGradient id="node" cx="0.34" cy="0.28" r="0.9">
+      <stop offset="0" stop-color="#7EE2A8"/>
+      <stop offset="0.5" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#2EA043"/>
+    </radialGradient>
+  </defs>
+
+  <rect width="1280" height="640" fill="url(#bg)"/>
+  <rect width="1280" height="640" fill="url(#glow)"/>
+
+  <!-- wordmark + tagline -->
+  <text x="96" y="150" font-family="'SF Mono','JetBrains Mono','Fira Code',ui-monospace,Menlo,Consolas,monospace" font-size="112" font-weight="700" letter-spacing="-3" fill="#E6EDF3">Nemus</text>
+  <text x="100" y="204" font-family="ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="30" font-weight="500" fill="#7EE2A8">Multi-repo workspaces for the AI-agent era</text>
+
+  <!-- terminal window -->
+  <g transform="translate(96,258)">
+    <rect x="0" y="0" width="620" height="300" rx="16" fill="#161B22" stroke="#30363D" stroke-width="2"/>
+    <rect x="0" y="0" width="620" height="44" rx="16" fill="#0D1117"/>
+    <rect x="0" y="28" width="620" height="16" fill="#0D1117"/>
+    <circle cx="26" cy="22" r="7" fill="#FF5F56"/>
+    <circle cx="50" cy="22" r="7" fill="#FFBD2E"/>
+    <circle cx="74" cy="22" r="7" fill="#27C93F"/>
+    <text x="310" y="27" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="16" fill="#7D8590">nemus</text>
+
+    <g font-family="'SF Mono','JetBrains Mono',ui-monospace,Menlo,Consolas,monospace" font-size="22">
+      <text x="30" y="98"  fill="#7EE2A8">$ <tspan fill="#E6EDF3">nemus create payments</tspan></text>
+      <text x="30" y="140" fill="#7D8590">✓ cloned 12 repositories</text>
+      <text x="30" y="182" fill="#7D8590">✓ wrote AGENTS.md · installed skills</text>
+      <text x="30" y="224" fill="#7EE2A8">$ <tspan fill="#E6EDF3">nemus -- "start the checkout refactor"</tspan></text>
+      <text x="30" y="266" fill="#3FB950">▸ launching agent<tspan fill="#3FB950">█</tspan></text>
+    </g>
+  </g>
+
+  <!-- mark on the right -->
+  <g transform="translate(858,150) scale(1.5)">
+    <g fill="none" stroke-linecap="round">
+      <path d="M120 210 L120 150 Q120 140 128 132 L150 108" stroke="url(#edge)" stroke-width="20"/>
+      <path d="M122 158 Q108 140 86 128 L70 118" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M128 132 L128 78" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M86 128 L70 92" stroke="#238636" stroke-width="9"/>
+    </g>
+    <g>
+      <circle cx="150" cy="104" r="15" fill="url(#node)"/>
+      <circle cx="150" cy="104" r="15" fill="none" stroke="#7EE2A8" stroke-width="2.5" opacity="0.9"/>
+      <circle cx="128" cy="74"  r="13" fill="url(#node)"/>
+      <circle cx="70"  cy="114" r="12" fill="url(#node)"/>
+      <circle cx="70"  cy="88"  r="9"  fill="url(#node)"/>
+      <circle cx="120" cy="212" r="10" fill="#2EA043"/>
+    </g>
+  </g>
+</svg>

package/assets/icon.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Nemus icon">
+  <title>Nemus</title>
+  <defs>
+    <linearGradient id="tile" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#1F7A34"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="256" height="256" rx="58" fill="url(#tile)"/>
+
+  <!-- tree carved out of the green (negative space); canopy = 3 lobes -->
+  <g fill="#0D1117">
+    <rect x="118" y="150" width="20" height="70" rx="9"/>
+    <circle cx="128" cy="106" r="54"/>
+    <circle cx="84"  cy="138" r="30"/>
+    <circle cx="172" cy="138" r="30"/>
+  </g>
+
+  <!-- terminal wink: a ">" prompt + cursor cut back in green inside the canopy -->
+  <path d="M108 90 l22 18 -22 18" fill="none" stroke="#56D364" stroke-width="11" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="140" y="115" width="26" height="11" rx="5.5" fill="#56D364"/>
+</svg>

package/assets/logo-wordmark.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 200" width="640" height="200" role="img" aria-label="Nemus">
+  <title>Nemus</title>
+  <defs>
+    <linearGradient id="edge" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#1F7A34"/>
+    </linearGradient>
+    <radialGradient id="node" cx="0.34" cy="0.28" r="0.9">
+      <stop offset="0" stop-color="#7EE2A8"/>
+      <stop offset="0.5" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#2EA043"/>
+    </radialGradient>
+  </defs>
+
+  <!-- mark -->
+  <g transform="translate(-14,-22) scale(0.82)">
+    <g fill="none" stroke-linecap="round">
+      <path d="M120 210 L120 150 Q120 140 128 132 L150 108" stroke="url(#edge)" stroke-width="20"/>
+      <path d="M122 158 Q108 140 86 128 L70 118" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M128 132 L128 78" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M86 128 L70 92" stroke="#238636" stroke-width="9"/>
+    </g>
+    <g>
+      <circle cx="150" cy="104" r="15" fill="url(#node)"/>
+      <circle cx="150" cy="104" r="15" fill="none" stroke="#7EE2A8" stroke-width="2.5" opacity="0.9"/>
+      <circle cx="128" cy="74"  r="13" fill="url(#node)"/>
+      <circle cx="70"  cy="114" r="12" fill="url(#node)"/>
+      <circle cx="70"  cy="88"  r="9"  fill="url(#node)"/>
+      <circle cx="120" cy="212" r="10" fill="#2EA043"/>
+    </g>
+  </g>
+
+  <!-- wordmark: mid-green reads on light AND dark -->
+  <text x="196" y="130" font-family="'SF Mono','JetBrains Mono','Fira Code',ui-monospace,Menlo,Consolas,monospace" font-size="104" font-weight="700" letter-spacing="-3" fill="#2EA043">Nemus</text>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Nemus">
+  <title>Nemus</title>
+  <defs>
+    <linearGradient id="edge" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#1F7A34"/>
+    </linearGradient>
+    <radialGradient id="node" cx="0.34" cy="0.28" r="0.9">
+      <stop offset="0" stop-color="#7EE2A8"/>
+      <stop offset="0.5" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#2EA043"/>
+    </radialGradient>
+  </defs>
+
+  <!-- an asymmetric sapling that doubles as a git commit graph -->
+  <g transform="translate(18,8)">
+    <g fill="none" stroke-linecap="round">
+      <path d="M120 210 L120 150 Q120 140 128 132 L150 108" stroke="url(#edge)" stroke-width="20"/>
+      <path d="M122 158 Q108 140 86 128 L70 118" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M128 132 L128 78" stroke="url(#edge)" stroke-width="13"/>
+      <path d="M86 128 L70 92" stroke="#238636" stroke-width="9"/>
+    </g>
+    <g>
+      <circle cx="150" cy="104" r="15" fill="url(#node)"/>
+      <circle cx="150" cy="104" r="15" fill="none" stroke="#7EE2A8" stroke-width="2.5" opacity="0.9"/>
+      <circle cx="128" cy="74"  r="13" fill="url(#node)"/>
+      <circle cx="70"  cy="114" r="12" fill="url(#node)"/>
+      <circle cx="70"  cy="88"  r="9"  fill="url(#node)"/>
+      <circle cx="120" cy="212" r="10" fill="#2EA043"/>
+    </g>
+  </g>
+</svg>