From def12c51ca6ed0ac00a22efbb8bf0148608406cd Mon Sep 17 00:00:00 2001
From: Willie
Date: Fri, 29 May 2026 22:35:09 +0800
Subject: [PATCH] chore: update docs
---
CHANGELOG.md | 35 +++++++++++++++++++
README.md | 5 ++-
skills/skillshare/SKILL.md | 2 +-
website/docs/troubleshooting/common-errors.md | 33 +++++++++++++++++
website/src/pages/changelog.md | 35 +++++++++++++++++++
5 files changed, 108 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f6b0b8af..2f9204ea9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,40 @@
# Changelog
+## [0.20.0] - 2026-05-29
+
+### New Features
+
+#### Git scope control (`git_root`)
+
+- **`git_root` scope** — choose which directory `skillshare commit`, `push`, and `pull` version. The default stays your skills source, but you can point git at `agents`, `extras`, or `root` (skills + agents + extras together in a single repo). Set it during init, or switch later on an existing setup:
+ ```bash
+ skillshare init --git-root root # version skills, agents, and extras in one repo
+ skillshare init --git-root agents # switch scope headlessly later
+ ```
+ A `root`-scope repo automatically keeps `config.yaml` out of version control (it holds machine-specific paths), and nested git repositories are detected and blocked before they would upload as empty submodules. If `git_root` points to a scope whose directory has no repo, `commit`/`push`/`pull` print a "Git root mismatch" error with the exact commands to fix it.
+- **Switch scope from the dashboard** — the Git Sync page can change the `git_root` scope, set the git remote during the switch, and offers a one-click action when the scoped directory isn't a repository yet.
+
+#### Extras extension transforms
+
+- **`extension` field on extras targets** — convert Markdown into a tool's native format during sync, for tools that don't read Markdown. Reference extensions ship for Gemini CLI (TOML commands) and Codex CLI (TOML agents):
+ ```yaml
+ extras:
+ - name: commands
+ targets:
+ - path: .gemini/commands
+ extension: gemini-commands # transforms .md → .toml during sync
+ ```
+ Transforms run source → target only (`extras collect` skips them), use `copy` semantics, and never overwrite a local file or directory without `--force`. The Codex agents extension maps `name`, `description`, and `model` from frontmatter.
+- **Manage extensions from the dashboard** — the Config page lists installed extensions with descriptions and guards against removing one that is still in use; the Extras page and Add Extra modal include a per-target extension picker.
+
+#### List filtering
+
+- **Filter skills by enabled/disabled status** — press `s` in the `list` TUI to cycle All → Enabled → Disabled, or use the `s:enabled` / `s:disabled` tag to combine status with other filters. The dashboard Resources page gains the same status filter.
+
+### Bug Fixes
+
+- **Hardened git remote handling** — remote URLs beginning with `-` (which git could misinterpret as a flag) are now rejected when setting or adding a remote, including via `skillshare init --remote`.
+
## [0.19.24] - 2026-05-27
### New Features
diff --git a/README.md b/README.md
index 8a3fb5aea..0551f3af5 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@
> [!NOTE]
-> **Latest**: [v0.19.24](https://github.com/runkids/skillshare/releases/tag/v0.19.24) — `skillshare commit` creates local git checkpoints without pushing; the Git Sync page now supports **Commit locally**. [All releases →](https://github.com/runkids/skillshare/releases)
+> **Latest**: [v0.20.0](https://github.com/runkids/skillshare/releases/tag/v0.20.0) — choose what `commit`/`push`/`pull` version with **git_root scope** (skills, agents, extras, or all together in one repo); extras **extension transforms** convert Markdown to native formats (Gemini TOML commands, Codex TOML agents) during sync. [All releases →](https://github.com/runkids/skillshare/releases)
## Why skillshare
@@ -277,6 +277,9 @@ Thanks to everyone who helped shape skillshare.
+
+
+
---
diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md
index 086f4f126..5c4297095 100644
--- a/skills/skillshare/SKILL.md
+++ b/skills/skillshare/SKILL.md
@@ -15,7 +15,7 @@ description: |
`.agentignore` and `enable`/`disable` for per-agent toggles.
argument-hint: "[command] [target] [--json] [--dry-run] [-p|-g]"
metadata:
- version: v0.19.24
+ version: v0.20.0
---
# Skillshare CLI
diff --git a/website/docs/troubleshooting/common-errors.md b/website/docs/troubleshooting/common-errors.md
index e10d3d1b8..c6e7a89fe 100644
--- a/website/docs/troubleshooting/common-errors.md
+++ b/website/docs/troubleshooting/common-errors.md
@@ -205,6 +205,39 @@ git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```
+### `Git root mismatch`
+
+**Cause:** `git_root` in `config.yaml` points to a scope directory that has no git repo, but another scope directory does. This happens when you change `git_root` without relocating the repository — switching scope means "start versioning a different directory", not "move the existing history". See [`git_root`](/docs/reference/targets/configuration#git-root).
+
+**Solution:** Pick one of the three options the error prints:
+```bash
+# Start a fresh repo at the configured scope (no history)
+skillshare init --git-root
+
+# Move the existing repo over, keeping history
+mv /.git /.git
+
+# Or keep using the existing repo: set git_root back in config.yaml
+# git_root:
+```
+
+### `nested git repositories must be disabled first`
+
+**Cause:** With `git_root: root`, a subdirectory (e.g. a tracked skill repo under `skills/_org/`) has its own `.git`. Git would upload it as an **empty submodule**, silently dropping its files, so `commit`/`push` abort until each nested repo is disabled.
+
+**Solution:**
+```bash
+# Disable each reported nested repo (reversible — just rename back to re-enable)
+mv ~/.config/skillshare//.git ~/.config/skillshare//.git.disabled
+```
+Or use the one-click disable on the web UI Git Sync page. skillshare also keeps `config.yaml` out of a root-scope repo automatically (it holds machine-specific paths).
+
+### `Invalid git_root`
+
+**Cause:** `git_root` in `config.yaml` is set to an unrecognized value (e.g. a typo).
+
+**Solution:** Use one of `skills`, `agents`, `extras`, or `root` — or leave it empty (defaults to `skills`).
+
---
## Install Errors
diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md
index 868f9b19e..a3bb606a1 100644
--- a/website/src/pages/changelog.md
+++ b/website/src/pages/changelog.md
@@ -9,6 +9,41 @@ All notable changes to skillshare are documented here. For the full commit histo
---
+## [0.20.0] - 2026-05-29
+
+### New Features
+
+#### Git scope control (`git_root`)
+
+- **`git_root` scope** — choose which directory `skillshare commit`, `push`, and `pull` version. The default stays your skills source, but you can point git at `agents`, `extras`, or `root` (skills + agents + extras together in a single repo). Set it during init, or switch later on an existing setup:
+ ```bash
+ skillshare init --git-root root # version skills, agents, and extras in one repo
+ skillshare init --git-root agents # switch scope headlessly later
+ ```
+ A `root`-scope repo automatically keeps `config.yaml` out of version control (it holds machine-specific paths), and nested git repositories are detected and blocked before they would upload as empty submodules. If `git_root` points to a scope whose directory has no repo, `commit`/`push`/`pull` print a "Git root mismatch" error with the exact commands to fix it.
+- **Switch scope from the dashboard** — the Git Sync page can change the `git_root` scope, set the git remote during the switch, and offers a one-click action when the scoped directory isn't a repository yet.
+
+#### Extras extension transforms
+
+- **`extension` field on extras targets** — convert Markdown into a tool's native format during sync, for tools that don't read Markdown. Reference extensions ship for Gemini CLI (TOML commands) and Codex CLI (TOML agents):
+ ```yaml
+ extras:
+ - name: commands
+ targets:
+ - path: .gemini/commands
+ extension: gemini-commands # transforms .md → .toml during sync
+ ```
+ Transforms run source → target only (`extras collect` skips them), use `copy` semantics, and never overwrite a local file or directory without `--force`. The Codex agents extension maps `name`, `description`, and `model` from frontmatter.
+- **Manage extensions from the dashboard** — the Config page lists installed extensions with descriptions and guards against removing one that is still in use; the Extras page and Add Extra modal include a per-target extension picker.
+
+#### List filtering
+
+- **Filter skills by enabled/disabled status** — press `s` in the `list` TUI to cycle All → Enabled → Disabled, or use the `s:enabled` / `s:disabled` tag to combine status with other filters. The dashboard Resources page gains the same status filter.
+
+### Bug Fixes
+
+- **Hardened git remote handling** — remote URLs beginning with `-` (which git could misinterpret as a flag) are now rejected when setting or adding a remote, including via `skillshare init --remote`.
+
## [0.19.24] - 2026-05-27
### New Features