forgemap 0.4.1-dev-main.48-b1e759e → 0.4.1

package/README.md

@@ -11,8 +11,6 @@
 [![Node Version](https://img.shields.io/node/v/forgemap.svg?style=flat-square&color=8993be)](https://www.npmjs.com/package/forgemap)
 [![License: MIT](https://img.shields.io/npm/l/forgemap.svg?style=flat-square&color=10b981)](LICENSE)
 
-![forgemap demo](.github/assets/demo.gif)
-
 </div>
 
 ---
@@ -37,41 +35,53 @@ That's it. Every repo lands at a predictable `<root>/<forge.dir>/<owner>/<repo>`
 - **🧰 Typed config** — `forgemap.config.ts` with `defineForgeMapConfig()`, parent walk-up discovery, and a global fallback.
 - **🚀 Shell-friendly** — `forgemap shell-init --install` wires up real `forgemap cd <slug>` **and** tab-completion in one step.
 
-## 📦 Install & run
-
-> [!IMPORTANT]
-> Needs **Node 24+** and **`git`** on `PATH`. [`gh`](https://cli.github.com/) (GitHub CLI) is only required when a `type: 'github'` forge is configured — run `forgemap validate` for an exact rundown of what your config needs.
+## 📦 Installation
 
 ```bash
-npm install -g forgemap   # or: pnpm add -g forgemap
+npm install -g forgemap
+# or
+pnpm add -g forgemap
+```
 
-cd ~/projects                            # the directory that should hold all your repos
-forgemap config init                     # write a starter forgemap.config.ts
-forgemap shell-init --install            # cd wrapper + completion → your rc file (idempotent)
-source ~/.zshrc                          # re-source once, then it's automatic
+**Requirements**
 
-forgemap clone kirchDev/laravel-pbac     # any slug form works: owner/repo, forge:owner/repo, URL, SSH
-forgemap cd laravel                      # fuzzy match → jump in; bare `forgemap cd` opens a picker
-```
+- Node 24+
+- `git` on `PATH`
+- [`gh`](https://cli.github.com/) (GitHub CLI) — only when a `type: 'github'` forge is configured
 
-`forgemap cd` resolves the slug, walks/picks across your cloned repos, and actually changes directory because the shell wrapper from `shell-init` intercepts it before the binary runs. Every other subcommand falls through to the real binary unchanged. Hacking on forgemap itself? See [CONTRIBUTING.md → Trying the CLI locally](CONTRIBUTING.md#trying-the-cli-locally) — covers `pnpm setup`, `pnpm link --global .` and the shell-wrapper source.
+Run `forgemap validate` after setup for an exact rundown of what's needed for your config.
 
-<details>
-<summary><strong>All commands</strong> — clone, cd, search, open, sync/status, import, cleanup, validate, shell-init, config</summary>
+Hacking on forgemap itself? See [CONTRIBUTING.md → Trying the CLI locally](CONTRIBUTING.md#trying-the-cli-locally) — covers `pnpm setup`, `pnpm link --global .` and the shell-wrapper source.
 
-### Clone & jump
+## 🚀 Quick start
 
 ```bash
-forgemap clone kirchDev/laravel-pbac     # default forge
+# 1. Pick a directory that should hold all your repos and drop a config there.
+cd ~/projects
+forgemap config init
+
+# 2. Wire up the shell integration once — real `forgemap cd` + tab-completion.
+forgemap shell-init --install            # appends loaders to ~/.zshrc (or bashrc/fish)
+source ~/.zshrc                          # re-source once, then it's automatic
+# Prefer manual? eval "$(forgemap shell-init)"   ·   fish: forgemap shell-init fish | source
+
+# 3. Clone — any slug form works.
+forgemap clone kirchDev/laravel-pbac
 forgemap clone github:TitusKirch/forgemap
 forgemap clone https://github.com/foo/bar
 
+# 4. Jump into a repo from anywhere.
 forgemap cd kirchDev/laravel-pbac        # exact slug → direct cd
 forgemap cd laravel                      # fuzzy single match → direct cd
 forgemap cd kirch                        # multiple matches → interactive picker
 forgemap cd                              # no arg → picker over every clone
 ```
 
+`forgemap cd` resolves the slug, walks/picks across your cloned repos,
+and actually changes directory because the shell wrapper from
+`shell-init` intercepts it before the binary runs. Every other
+subcommand falls through to the real binary unchanged.
+
 ### Search and pick on demand
 
 ```bash
@@ -144,7 +154,6 @@ Validates the schema, required CLI tools (`git` always, `gh` when a `type: 'gith
 forgemap shell-init --install        # cd wrapper + completion → your rc file (idempotent)
 forgemap completion --install        # completion only, if you don't want the cd wrapper
 forgemap shell-init                  # print the wrapper (manual: eval "$(…)")
-forgemap shell-init fish | source    # fish: source the wrapper directly
 forgemap completion bash             # print the completion script for bash/zsh/fish
 ```
 
@@ -157,8 +166,6 @@ forgemap config init                 # write a starter forgemap.config.ts
 forgemap config show                 # print the resolved config + which file it came from
 ```
 
-</details>
-
 ## ⚙️ Configuration
 
 `forgemap config init` writes a `forgemap.config.ts` like this:
@@ -185,14 +192,6 @@ export default defineForgeMapConfig({
 });
 ```
 
-The config is discovered by walking **up** from your current directory (so `forgemap cd` works from inside any clone), then falling back to `~/.config/forgemap/`. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
-
-> [!TIP]
-> Already have a directory full of repos? Skip writing this by hand — `forgemap import <path>` derives `root` + `forges` from the existing layout.
-
-<details>
-<summary><strong>All configuration options</strong></summary>
-
 | Key                  | What it controls                                                                                          |
 | :------------------- | :-------------------------------------------------------------------------------------------------------- |
 | `root`               | Base directory for all clones. Relative paths resolve against the config file's directory.                |
@@ -204,10 +203,10 @@ The config is discovered by walking **up** from your current directory (so `forg
 
 The config file is discovered by walking **up** from your current directory (so `forgemap cd` works from inside any clone, not just the root), then falling back to a global `$XDG_CONFIG_HOME/forgemap/forgemap.config.*` (i.e. `~/.config/forgemap/`) so commands work from anywhere. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
 
-</details>
+> [!TIP]
+> Already have a directory full of repos? Skip writing this by hand — `forgemap import <path>` derives `root` + `forges` from the existing layout.
 
-<details>
-<summary><strong>Repo layout &amp; slug syntax</strong></summary>
+## 🗂️ Layout
 
 ```
 <root>/
@@ -228,6 +227,8 @@ Example with the default config rooted at `~/projects`:
         └── forgemap/
 ```
 
+## 🚪 Slug syntax
+
 | Form                                | Resolves to                                            |
 | :---------------------------------- | :----------------------------------------------------- |
 | `kirchDev/laravel-pbac`             | Default forge, `kirchDev/laravel-pbac`.                |
@@ -236,14 +237,7 @@ Example with the default config rooted at `~/projects`:
 | `https://github.com/foo/bar.git`    | Same, `.git` suffix stripped.                          |
 | `git@github.com:foo/bar.git`        | SSH form, host matched against `forges[].host`.        |
 
-</details>
-
-## 🤝 Contributing
-
-PRs welcome. Conventional Commits required (enforced via commitlint); Husky runs lint-staged on every commit. Run `pnpm check:fix` before pushing — CI will catch what husky missed.
-
-<details>
-<summary><strong>Dev scripts</strong></summary>
+## 🧪 Testing
 
 ```bash
 pnpm install
@@ -255,7 +249,12 @@ pnpm bench        # microbench scanRepos / cache hit / cache rebuild
 
 Tune the bench layout via env vars (`FORGEMAP_BENCH_FORGES`, `FORGEMAP_BENCH_OWNERS`, `FORGEMAP_BENCH_REPOS`, `FORGEMAP_BENCH_RUNS`).
 
-</details>
+## 🤝 Contributing
+
+PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs lint-staged on every commit.
+
+> [!TIP]
+> Run `pnpm check:fix` before pushing — CI will catch what husky missed.
 
 ## 🛣️ Versioning
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "forgemap",
-  "version": "0.4.1-dev-main.48-b1e759e",
+  "version": "0.4.1",
   "description": "CLI that manages a local repo layout grouped by git server, organization and repository name.",
   "keywords": [
     "cli",