GitHub links to tree/HEAD/... when it means the default branch. Since
URL refs became clone refs, HEAD was taken as a branch name: with a
subdir the ref lookup failed, without one git clone --branch HEAD
failed. These URLs installed fine before, so keep them on the default
branch.
Refs #293
* feat(install): pin GitHub tree/blob URLs to their ref
Hub entries only carry a source URL, so a team hub had no way to pin a
third-party skill to a reviewed tag or commit. The parser already read
tree/<ref>/ and blob/<ref>/ URLs but discarded the ref, installing from
the default branch instead of the version the URL names.
Keep that ref as Source.Branch. An explicit --branch (CLI) or branch
(API body) still overrides it; the server handlers now only override
when a branch is given. Batch installs group by repo and ref so two
pinned versions of one repo get separate clones.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs(install): describe pinning hub sources to a tag or commit
Explain that a GitHub tree/<ref>/ source URL pins the install, in both
the hub index guide and the install reference.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(install): pin GitLab/Bitbucket URLs and resolve refs containing "/"
Pinning should not depend on the host, so GitLab (-/tree/<ref>/) and
Bitbucket (src/<ref>/) web URLs now keep their ref too.
Taking the first path segment as the ref broke branch names containing
"/": tree/feature/x/skills/foo cloned branch "feature" and failed. When
the first segment is not a branch or tag on the remote, the longest
matching one is used instead. A ref the remote does not have fails
with a hint to use --branch, rather than silently installing the
default branch. A saved branch that covers more of the path (from
--branch or config) moves the subdir without asking the remote.
The grouped-install round-trip test pinned -/tree/main/ against a repo
on master; the ref used to be ignored, so its branch is now renamed.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs(install): cover GitLab, Bitbucket and "/" branches in URL pinning
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(install): keep web URL refs correct on reinstall, --branch and grouping
Review of the slash-branch resolution found four gaps:
- A saved branch equal to the whole URL tail (tree/feature/x) did not
move the subdir back, so every reinstall or update looked for "x".
- An unrelated --branch with a slash-branch URL kept the parse-time
subdir (x/skills/foo) instead of the URL's real one.
- Grouped installs copy the source to a repo root; resolution then put
the subdir back and discovery looked under a doubled path. Grouping
also keyed on the unresolved first segment, so tree/feature/x and
tree/feature/y could share one clone. Web URLs with a ref now install
on their own, and resolution leaves a repo-root copy at its root.
- A skill named after the parse-time subdir kept that name once the
path turned out to be all ref (tree/feature/x named the skill "x").
The unknown-ref error now reads as a missing ref first, since a stale
ref (tree/master after a rename) is more common than a slash branch.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(update): keep legacy installs on the default branch
Skills installed before URL refs were honoured got the default branch
and recorded no branch. Single-skill update re-parses the recorded
source, so it moved them to the URL's ref (or failed on a stale one,
with a hint to pass --branch, which update does not accept), while
update --all rebuilds from RepoURL and kept the default branch.
ApplyRecordedBranch treats an empty recorded branch as the remote
default and drops the URL's ref. It replaces the branch handling at
every site that reinstalls from recorded metadata: CLI and server
update for skills and agents, and tracked-repo rehydration.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* perf(search): share one clone across pinned hub skills from a repo
Any web URL with a path after its ref installed on its own, so a hub
listing many tree/<tag>/ skills from one repo cloned it once per skill.
groupByRepo now resolves each URL's ref before grouping, with a
RemoteRefs cache that lists each remote's refs once, and groups by
repo and resolved ref. Only refs containing "/" (whose subdir the
discovery match cannot re-derive) and refs that fail to resolve still
install alone. A resolved source is marked settled so the grouped
clone does not resolve it again, and ApplyRecordedBranch settles the
subdir from a recorded branch without asking the remote.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Willie <egg358358@gmail.com>
Every row repeated the same row of target chips, so recent backups were
hard to tell apart, and restoring meant picking a backup and then a
folder in a second dialog step.
Backups are now grouped by day with a compact row per backup. Opening a
row lists each folder with its file count and size and its own Restore
button; Copy path and Delete moved into that panel.
The page also says what it is doing: a list-shaped skeleton with
"Loading backups…" while the list is read, and a progress note while
Back up now runs, instead of a generic card skeleton and a lone button
spinner that read as a frozen page.
The list endpoint walked every snapshot to size it, then walked all of
them again for the total. With thousands of files and a cold file cache
(right after an upgrade, for example) the Backup page took visibly long
to open.
Each snapshot folder is now walked once for both its size and file
count. Backup and total sizes are sums of those, and the per-folder
counts are returned as `entries` so the dashboard can show what each
folder holds.
`skillshare upgrade` already downloads the new version's UI assets, and
that download removes older versions. Restarting with clearCache then
deleted the fresh assets, so the new server had to fetch them from GitHub
again before it could answer. On a slow connection that outlasted the
dialog's 20-second reconnect wait and left the page looking stuck.
If the pre-download failed, the restarted server still downloads the
assets because none are cached.
Counted labels such as "{count} skills" had only a plural form, so the
dashboard showed "1 skills", "1 of 1 targets", "1 backups" and similar.
Each such label now has a .one and a .other form in every locale, and
the call sites pick by count, as the rest of the dashboard already does.
The dashboard screenshots predated the Projects page and showed codex at
its old path, and the guides for dashboard-only features (AGENTS.md
sharing, MCP, plugins, backups, hubs) had no pictures at all.
- Re-shoot the dashboard screenshots (docs and README copies) and add
ones for targets, extras, shared AGENTS.md, MCP, project MCP, plugins,
backups, hubs and project mode.
- Add diagrams for sharing AGENTS.md, MCP sync and migrating with
collect; fix codex's path in the getting-started diagram.
- Replace terminal screenshots with real output as text, and remove
images nothing referenced.
- Fix text that no longer matched the dashboard (project mode, hub
navigation, backup list output).
The project-mode note on the dashboard still said Git sync and Backup
are not shown, but Settings › Backup now appears in project mode,
scoped to the project.
The dashboard lists a project's agent snapshots, but `backup --list -p`
and `backup --cleanup -p` were refused with "not supported in project
mode", so the CLI could only see the global folder. Both now work on
.skillshare/backups/ with -p.
Refs #299
Describe the new backup commands (--delete, backup files list/show/
restore), the reasons recorded with file backups, and the three sections
of the dashboard's Backup tab, and point the AGENTS.md backups section
there instead of telling readers to copy files back by hand.
Refs #299
The Backups tab only listed target snapshots and was hidden in project
mode, while file backups had no view at all and MCP backups sat in a
dialog on the MCP page. The tab now has three sections: target folders
(filter, copy path, delete one snapshot), files (each version with why
it was taken, a diff or full-text preview, and restore) and MCP (grouped
by agent config, opening the existing restore dialog). It is shown in
project mode too, scoped to the project.
Refs #299
skillshare backs up AGENTS.md, CLAUDE.md and shared-file locations before
rewriting them, but nothing could list or restore those copies, and a
target snapshot could not be deleted on its own. The file backups now
record why they were taken in their name (<time>.<reason>.bak; older ones
have none), and the server and CLI can list them, show a version and
restore it, saving the current content first. A link is only replaced
when the caller asks for it.
Also:
- DELETE /api/backups/{timestamp} and `backup --delete`.
- Agents snapshots (<target>-agents) could not be restored from the
dashboard: the name was looked up as a target.
- Project mode uses the project's backups folder for snapshots and lists
only file backups inside the project.
- MCP backups report which servers they changed and when.
Refs #299
The project Extras page no longer has a file-name field on folder
targets; shared files and their locations moved to the AGENTS.md tab.
Document the project differences (root-relative folders, tool files
allowed, relative links) and update the unreleased changelog entry.
Refs #299
Single-file extras in a project sat in the Folders tab and looked like
folder extras: a folder icon, folder modes and a flatten switch, with
no import mode and no sync on add. They now appear as shared-file cards
on the project AGENTS.md tab, reusing the global location rows and Add
location dialog with project-relative paths. The Folders tab lists only
folder extras in both modes, so the file-name field added there is gone.
The CJK location counts now say "locations", since the card header has
no heading next to it to give "2" its meaning.
Refs #299
In a project, single-file extras were only reachable through the folder
extras API, which has no file name, no import mode and no immediate
sync. The dashboard now shows them on the AGENTS.md tab like global
shared files, so the instructions routes it needs must work in project
mode: list, create, content, resolve and the locations routes.
A project location must stay inside the project (absolute, ~ and ..
paths are refused with instructions_location_outside_project) and is
stored relative, so a clone keeps working. A tool's own file is a valid
location in a project, so the is_target check is skipped there.
Refs #299
Gemini CLI is already a target, so the dashboard sends a GEMINI.md
location back to the Targets list; a notes folder with instructions.md
shows what --as is for.
Refs #299
An edited location only showed a hint, with no way to settle it. It now
gets the same collect and reapply note as a target row. The remove
dialog closes before removing, so the refetch no longer asks for the
preview of a location that is gone.
Refs #299
A location whose file was edited outside skillshare had no way to collect
or reapply, and a location whose config save failed stayed written on
disk. Resolve now takes a location path, and a failed save restores
what the file held; a failed reload keeps the saved location.
Refs #299
Show locations outside the tool list under the shared file, with an add
dialog for folder, file name and mode, a restore preview before removal,
and localized errors. The project Extras page takes a file name for
single-file extras.
Refs #299
The dashboard could only attach a shared AGENTS.md to known tools, while
the CLI's --add-target/--as already writes it to any folder under any
name. Add list/add/mode/remove/restore-preview routes for such locations,
syncing a new location right away and refusing folders in the way, tool
files and files held by another shared file. The extras add-target route
now accepts as and runs the same config validation as the CLI.
Refs #299
Document local preserved counts, the junction replacement warning,
the Convert dialog without a picker, the folder-in-the-way hint and
update progress so the docs match the dashboard and CLI.
Refs #299
Every rider row repeated the same line under its path on the AGENTS.md page, which is about instructions, not skills. The origin now shows when hovering the tool name.
Refs #299
"Run a sync" did not say where. The copy option now points at the Sync button that appears above the targets when the shared file changes elsewhere.
Refs #299
The copy option reused the Skills folder-copy text and glued a second sentence on with a space, which read oddly in Chinese. It now has one sentence about copying the shared file.
Refs #299
Mode changes, attach and the other AGENTS.md actions returned English
sentences, so a zh-TW dashboard showed "backed up ... before replacing
it" and "... is a directory" untranslated. Warnings are now
{code, params, message} and every instructions error carries a code,
so the dashboard shows them from i18n and falls back to the English
message for unknown codes. CLI output is unchanged.
Also from the Windows re-test:
- replacing a user's junction says so and where it pointed;
- status, doctor and sync agree on identical unowned copies (kept, not
linked), and an identical copy no longer suggests --force;
- the targets list shows a Developer Mode tooltip when file links are
unavailable;
- file names are taken from Windows paths too.
Refs #299
Windows acceptance on the local UTM guest was a pile of one-off
commands: finding utmctl, polling async exec, running as the desktop
user with a basic token, pinning builds, and pre-seeding the UI cache.
utm.sh wraps those steps, manual-setup.ps1 gives a one-line hands-on
setup in an isolated home, and the skill records the workflow and the
pitfalls hit along the way (S4U tokens, ARM64 emulation, zsh echo).
Refs #299
Updating many resources gave no sense of progress, and a failure was
easy to miss among the rest. The status card now shows a progress bar,
the row being updated gets a moving line and a pop when it finishes,
and blocked or failed updates move to their own section with a
one-line reason. Motion is off under prefers-reduced-motion.
A real directory at a target path showed the generic drift hint ("sync
will change it back") although sync refuses to replace a directory. The
assignment now carries reason "directory" and the row says to remove or
rename the folder.
The restore plan read "personal stay" in English because the kept-files
line had no singular form.
Refs #299
Connect-all still planned to switch a target that another shared file
holds in copy mode (the API marks only links as linked_shared), which
would silently take it from that file. Any link or copy assignment now
marks the target as held, so the switch step is gone.
The header tabs sat on the strip's divider; they are now centred with
room under the underline.
Refs #299
Exploratory CLI, dashboard and real-Windows testing of single-file extras
found paths that corrupted another shared file, lost user content, or
reported the wrong state.
- One shared file per link/copy target is now enforced in config
validation, so the CLI, sync and API all refuse it; an import is never
written through a link into another shared file (409
instructions_target_held in the API).
- Restore recreates an original Windows junction as a junction, which
needs no privilege, and remove restores before saving config so a
failed restore no longer orphans the record.
- Imports into dotfiles links, damaged managed blocks, repointed links
and CRLF files keep the user's content; project imports use paths
relative to the file so a moved repo keeps working.
- Mode and assign responses carry sync warnings; dry-run says when an
edit would be backed up; invalid modes no longer show as healthy.
- An edited copy reports modified, identical unowned copies count as
synced without being owned, and relative project links no longer show
drift.
- sync extras --json exits non-zero on errors; extras <name> --help
works; --add-target gains --as; detach messages match behavior.
Refs #299
Exploratory testing of the dashboard found edits lost without warning,
Cmd+S saving the page editor through an open dialog, and a connect-all
plan that would write an import through another shared file's link.
- Unsaved edits now ask before leaving the target tab, closing the edit
dialog, or reloading.
- Cmd+S does nothing to the page editor while a dialog is open.
- Connect-all skips targets already held by another shared file
(linked_shared), and 409 instructions_target_held shows its reason.
- Mode and attach warnings (such as a backed-up edit) show in a toast.
- Restore wording matches what restore does; the per-file connect time
was dropped because the record is per target file.
- Convert defaults to a new shared file; a new file is selected at once;
an unknown ?file= falls back and fixes the URL.
- The collapsed shared-file card scrolls instead of clipping.
- Change location is disabled while a shared file holds the target.
Refs #299
Review of the file-link fallback found paths that lost or misreported
user data:
- An identical local file was adopted as a skillshare copy and later
pruned without backup. Only files sync writes are tracked now.
- Clearing all own text in import mode was treated as no record, so
switching back resurrected the attach-time content.
- The mode API saved the new mode and returned success when a directory
blocked the sync; it now keeps the old mode and returns 409.
- Restore preview promised a delete for files restore leaves alone; both
now share one ownership decision.
- Prune forgot ownership even when removing the copy failed.
Refs #299
Every AGENTS.md box showed its size and view switch differently, which
read as clutter. One header strip now carries the live line count and
the Preview/Source switch everywhere; the read-only card opens in
Preview since that is what people read first.
The target page editor now saves with Cmd/Ctrl+S. An open editor
claims the shortcut so it no longer jumps to Sync while editing.
Read-only raw text wraps instead of scrolling sideways.
Refs #299
The sharing guide still told users to sync after every edit of a shared
file in copy mode, and did not mention the source/preview switch or that
empty rule folders drop out of the read order.
Refs #299
The edit/preview switch existed only on the target page, so the shared
file's editor, the new-file dialog and the read-only card still showed
raw Markdown. They now share one tab component: Edit | Preview in the
editors and Source | Preview on the read-only card, with previews built
from the unsaved draft.
The read order also listed rule folders such as claude's rules/*.md with
"0 files" for everyone who does not use them; empty folders are now left
out and a folder appears once it holds files.
Refs #299
Saving a shared AGENTS.md in the dashboard only wrote the source, so every
target in copy mode (including the Windows copy fallback) kept the old
content until someone found the sync button. Saving now rewrites that
file's copy targets through the regular extras sync, so an edited copy is
still backed up first, and the toast names the copies it updated. Link and
import targets already read the source and are left alone.
Refs #299
Switching a target from import to copy or symlink and back rebuilt the
file from the attach-time restore point, so lines the user wrote while in
import mode vanished (they survived only as a drift backup). Save the
file's own content when leaving import and rebuild from that on the way
back; the attach-time restore point itself is never re-recorded.
Refs #299
The docs said Windows always links with NTFS junctions and needs no admin
rights, which is only true for folders. Explain that single files need
Developer Mode for symlinks and otherwise sync as tracked copies, with the
warning line users will see and the folder-icon symptom from the issue.
Cover the per-target mode picker, the restore preview, changing a target's
file location, the single-column file tab with edit/preview, universal's
file list, and switching back to import. Also correct status and doctor
output that no longer matched the code, and the doctor "Link not
supported" advice, which pointed at Developer Mode although that check
creates a folder junction.
Refs #299
The legacy color constants in internal/ui (Red, Gray, Dim, Bold, Reset, …)
were compile-time strings that ignored the theme, so status, doctor, extras
list and about twenty other commands printed ANSI codes even with NO_COLOR
set. Make them variables and blank them at startup when the theme reports
NoColor, so the theme stays the single source of that decision. The two
places that hardcoded escape codes (usage and log --stats) now use the same
variables.
The AGENTS.md tab picked each target's mode for the user (import where
supported, a link elsewhere), which left Windows users without Developer
Mode no way out of a broken link and gave no copy option. Restore replaced
a file without showing what would come back, and only custom tools could
change which file a target reads.
- Each connected target gets a mode picker (import, symlink, copy); symlink
is unavailable when the machine cannot create file links, and a target
whose file is a folder link says so.
- Restore opens a preview of the file after restore and its diff.
- Every supported target can change its file location and name in a
dialog, with reset to default.
- The target file tab is a single column with the read order on one line,
a tinted managed import block, soft wrap, and an edit/preview switch;
universal lists the files of the tools that read its skills.
- The convert dialog shows only the methods that apply and a ready preview.
Refs #299