174 Commits
Author SHA1 Message Date
Willie 4bcd569e25 feat: MCP connections, plugins and a redesigned dashboard (v0.21.0) (#285)
* feat(mcp): sync portable server configuration across six clients

Add inline and external MCP sources with guided CLI and dashboard setup, native imports, conflict previews, ownership tracking, backups, and restore. Support Claude Code, Codex, Cursor, VS Code, OpenCode, and Grok CLI in global and project scopes.

Format YAML on save, document MCP fields in the config assistant, and keep its layout stable for scalar list items. Include schemas, localized UI copy, documentation, and regression and end-to-end coverage.

* fix(config): keep loading config when the MCP section is invalid

A mistake in the mcp section (an unknown key, a targets value that is
not a list, an invalid server field) made config.Load, LoadProject,
Save, SaveIn and ValidateConfig fail. Every command that reads config,
including skills sync, install, list and the dashboard, stopped working
because of settings it never uses.

MCPConfig now keeps a section that does not parse exactly as written and
records the error instead of returning it, so commands unrelated to MCP
load and save the config without touching that section. MCP commands
still validate their source on every run, and the dashboard config
editor calls the new ValidateMCP, so saving an invalid MCP section there
is still rejected.

Also correct the ProjectSources comment: sources.mcp resolves from the
directory containing config.yaml, not from the project root.

* fix(mcp): protect Agent files during concurrent edits and recovery

A release review of the MCP sync engine found ways it could lock users
out, report false conflicts, or change entries it does not own.

Recovery
- A failed write left pending.json behind, and every later MCP command
  refused to run. Failed writes now remove their journal, and a journal
  whose Agent file changed again is discarded, because ownership hashes
  still flag entries that no longer match.
- Preview no longer writes. It reads the ownership that recovery will
  record, byte for byte, so a preview stays valid across the recovery
  that the next write performs under the lock.

Concurrent Agent writes
- Claude Code rewrites ~/.claude.json on its own, so hashing whole files
  expired previews and failed applies. Revisions and pre-write checks
  now cover only the MCP entries, and apply rereads each file and applies
  the previewed entry edits to its current content, keeping settings the
  Agent wrote after the preview.

Comparison and ownership
- Only fields Skillshare renders are hashed, after dropping defaults
  Agents add or omit (type stdio/http, empty env, args or headers,
  enabled: true) and header name case, so equivalent entries are not
  reported as drift. enabled and disabled are compared, so turning off a
  managed server is a conflict instead of being overwritten.
- An unmanaged entry that already matches the source is reported as
  unchanged but no longer claimed, so removing the server never deletes
  an entry the user wrote. Import adopts it explicitly, and without
  --replace refuses to rewrite a differing entry, such as a literal token
  that import turned into an environment reference.
- Sync keeps Agent-only fields such as timeouts in existing entries.

Import
- Agent-only fields become warnings instead of blocking the import.
- streamable-http is accepted, and enabled/disabled flags are checked
  for every client.
- Values carrying a URL password, such as database DSNs, become
  environment references, and credential-like arguments are flagged.

Writes and state
- Save only renders the definition first, so a server that could never
  sync, such as one without targets, is rejected before it is saved.
- A symlinked config.yaml is written through to its target.
- TOML entries are updated in place, keep CRLF line endings, and repeated
  add/remove cycles no longer grow blank lines.
- JSON edits no longer HTML-escape characters such as &.
- GROK_HOME is honored.
- Backups keep the newest 20 per Agent file, pruned by file name, and
  damaged backup files are skipped instead of failing the list.
- GET /api/mcp no longer fails when an Agent that no server uses has an
  unresolvable path.

* feat(mcp): detect the client format of pasted JSON

Import without --from, the add wizard and the dashboard import API
assumed Claude's mcpServers shape unless a client was named, so VS Code
"servers" and OpenCode "mcp" snippets copied from server docs failed to
import. The client is now chosen by the top-level key, and a bare server
object still reads as Claude's single-entry shape.

TOML stays explicit because Codex and Grok share the format; a .toml
file without --from is still read as Codex.

* refactor(mcp): print CLI results through internal/ui

MCP commands wrote plain fmt output and duplicated statusFromErr, unlike
every other command. Plans, backup IDs and save/apply messages now use
the shared ui helpers, so they get the standard status prefixes and
colors; each change line shows the server name, action and target. The
operation log uses statusFromErr. --json output is unchanged.

* fix(server): serve MCP settings only to localhost or IP hosts

MCP settings include stdio commands that Agents execute, so a web page
must not be able to read or change them. The existing Origin check does
not stop DNS rebinding: once an attacker's domain resolves to 127.0.0.1,
the browser sends that domain as both Origin and Host from a loopback
address, and the dashboard also binds 0.0.0.0 in Docker.

Rebinding always needs a domain name, so every MCP route now also
requires a Host that is localhost or an IP literal, whatever the bind
address. Other dashboard routes are unaffected. Opening the dashboard
through a domain name, including a reverse proxy, therefore returns 403
for MCP settings; the message says to use localhost or an IP address,
because rewriting Host at the proxy would still fail the Origin check
and would reopen the hole.

Remove the unused POST /api/mcp/sync endpoint. Configuring with sync
covers it, and the guard wraps every remaining MCP route.

* fix(sync): make sync --all report MCP results reliably

- "sync -g mcp" and "sync --dry-run mcp" ran skills sync, because mcp
  was only recognized as the first argument. It now matches in any
  position.
- sync --all --json printed plain-text errors when the MCP preflight
  failed, and only an error on conflicts. Preflight errors now use the
  JSON error shape, and conflicts also return the credential-free plan so
  scripts can see which entries conflict.
- When resource sync failed, MCP was skipped without notice. Text output
  now warns that MCP settings were not applied; JSON output omits the mcp
  field, which --all otherwise always includes.
- MCP was applied with the preflight revision, which failed whenever the
  resource sync changed config or state in between. It is now planned
  again under the MCP lock, and conflicts found then still stop the
  write.

* fix(sync): recognize agents and extras after flags

sync only checked the first argument for a resource kind, so
"sync --dry-run agents" and "sync -g extras" silently synchronized
skills instead. Sync flags take no values, so the kind now matches in
any position.

The shared parseKindArg keeps its first-argument rule: uninstall, update
and similar commands accept resource names, and a name such as "agents"
must not be read as a kind.

* feat(ui): redesign the MCP dashboard around a server-by-agent matrix

The MCP page listed servers and planned changes as flat text, which made
it hard to see where each server is written and what needs attention.

- A matrix shows each server's status per Agent, summarizes pending
  changes and conflicts, and can hide synced entries. Agents whose MCP
  file or config directory exists are marked as detected; GET /api/mcp
  now returns the detected clients.
- Setup is a two-step dialog: add a remote URL, paste JSON or TOML, or
  import from an Agent, then preview which Agent files change. Importing
  an entry the Agent already has adopts it, Replace overrides only that
  entry, and a target selection equal to the inherited mcp.targets is
  saved without pinning targets on the server.
- Conflicts explain their cause and offer Import from <agent> or
  Replace. Removal lists the affected Agent files and offers removing
  from the source only or removing and syncing. Backups are grouped by
  day, with a preview before restoring a file.
- Agent icons appear on the MCP and Targets pages, and the universal
  target is marked as a path shared across agents. Brand icons come from
  @lobehub/icons-static-svg, with bundled SVGs for Warp and Zed.
- Segmented controls wrap instead of overflowing narrow containers.
- New copy is translated for every supported locale.

* fix(ui): let Sync all apply MCP after syncing resources

Sync all previewed MCP, synced skills, agents and extras, then applied
MCP with the revision from the first preview. When the resource sync
changed config or state, that revision was stale and MCP failed with
"preview again" after everything else had already been synced.

MCP is now rechecked before and after the resource sync by comparing the
reviewed changes (target, name and action) instead of the revision, and
applied with the fresh revision. A different set of changes still stops
before any MCP file is written.

* fix(ui): keep flow-style YAML collections when saving config

Formatting on save forced every collection into block style, so a
hand-written "targets: [claude, codex]" was expanded into a list each
time the config was saved. Each collection now keeps its flow or block
style, indentation is still normalized and comments are preserved, and
flow collections are not padded with spaces.

* docs(mcp): document ownership, normalization and dashboard host rules

- Explain that matching entries stay unmanaged until imported, so
  removing a server leaves them in place, and that import adopts an
  identical entry while --replace rewrites a differing one.
- Note that Agent defaults and header case are not treated as changes,
  that disabling a managed server is a conflict, and that previews stay
  valid while an Agent rewrites unrelated settings.
- Describe Agent-specific fields, streamable-http, GROK_HOME, backup
  retention, recovery by the next MCP write, and the VS Code limitation
  on environment references in headers.
- Document that MCP settings require opening the dashboard by localhost
  or an IP address, with SSH port forwarding for remote machines.
- Update the built-in skill for all six clients and the adoption rule,
  and the MCP runbook for import refusal, Agent-specific fields and
  pulled changes.

* docs(skill): streamline guidance and refresh resource workflows

Keep the built-in skill entrypoint focused and route agent and MCP details to dedicated references. Correct scope, audit, automation, and recovery guidance against the current CLI.

* feat(ui): redesign the dashboard around two styles and a flatter layout

The dashboard had grown page by page, so the same idea looked different
depending on where you met it and pages held controls with nothing to act on.
This rebuilds it on one token set that drives both the Clean and Playful styles
in light and dark, and reshapes the pages around what a person actually does.

Notable changes:

- MCP: replace the server-by-agent matrix with one row per server. The agents a
  server writes to are chips inside the row, so the list grows downwards as more
  CLIs gain MCP support instead of scrolling sideways.
- Settings: collect General, Backup, Log, Health, Extensions and Files into one
  page. The Files tab keeps a panel beside the editor showing what the field
  under the cursor does, the file's shape, or the unsaved changes.
- Audit rules: the YAML editor gets the same panel, plus a Test tab that runs a
  rule's regex against pasted lines.
- Skills and Agents become separate pages; install, search, updates and trash
  move into them. Old routes redirect.
- Tour: rewrite every step's copy, add MCP and Install steps, and anchor each
  step to a control that is always rendered so no step silently times out.
- Give every button a pointer cursor; the browser default does not say a button
  is clickable and each component class had to opt in by hand.

Docs follow the new Settings tabs and the MCP list.

* chore(devcontainer): move dev servers to uncommon ports

5173, 19420 and 8888 are defaults that other projects on the same
machine already hold, so `make devc` failed to bind and the container
never started. Use 45173, 49420 and 48888 instead, identical inside and
outside the container so every banner, log and doc prints the URL that
actually works.

* feat(ui): link dashboard source counts to their pages

The counts in the playful dashboard's source note named a number but led
nowhere, so reaching Skills or MCP from there meant going back to the
sidebar. Each row is now a link to its own page.

The hover fill uses currentColor because .ss-pinnote.src overrides the ink
tokens for the yellow note.

* feat(ui): build and browse hubs from the dashboard

A hub is a JSON index that lists skills, and until now the web UI could
only consume one someone else had already hosted. Writing the index by
hand was the only way to produce one, and the two halves never met: the
dialog that searched hubs and the page that would have built one shared a
config file but nothing else.

The new /hubs page holds both halves behind two tabs:

  Browse   pick a hub, filter its contents by tag or text, install from it
           without leaving the page
  My hubs  assemble an index from installed skills, validate it, export it

A draft is offered as a source in Browse straight away, read from the
draft API rather than a file, so you can see what a recipient sees before
deciding whether to host anything. Where the index is hosted is stored on
the draft and stripped from the exported document, so a reopened hub
remembers where it was published and the published file stays clean.

Hub management moves out of the install dialog, which keeps only the
search-source dropdown and links here.

Routing switches to createBrowserRouter for useBlocker, which guards the
builder against navigating away from unsaved entries.

* docs(extras): add shared instructions recipe for AGENTS.md across agents

Answers a recurring question about sharing one instruction file between AI
agents: extras already covers it, since each agent keeps its user-level
copy in its own directory and one extra can target all of them.

Naming the source file AGENTS.md rather than something neutral matters —
Codex concatenates AGENTS.md files and has no import syntax, so it only
recognises the file by name. Claude Code and Antigravity read a fixed
filename of their own but resolve @-imports, so a one-line CLAUDE.md or
GEMINI.md picks up the synced file.

Says plainly that this is not agent memory. Agents keep their own
learnings in private stores — a Markdown directory for Claude Code, a
database for Codex, non-file storage for Cursor — so that side is a
migration problem, not something syncing files can solve.

* feat(ui): filter skills and agents by target

The Targets column showed which targets a resource reaches, but there was
no way to narrow the list down to one. The filter reads the sync matrix —
the same source that column renders — so a result always matches the icons
the rows show.

Options and counts are derived from the matrix, so no target is offered
that would filter to nothing, and the control stays hidden until at least
two targets have something. A selected target that disappears on a kind
switch or an uninstall falls back to All rather than emptying the list.

The toolbar had 24px to spare at 1440px, so the new control wrapped the
row. Source moves from a 325px segmented control to a dropdown like its
neighbours, and every filter now sizes to its label instead of a fixed
width that truncated the longer values.

* fix(ui): tighten page headers and reach hubs from skills

PageHeader carried mb-7 while .ss-wrap already separates its children with a
28px flex gap. Margins and flex gaps add up rather than collapse, so every
page inside the wrapper opened with a 56px hole under its title. Move the
default onto .ss-pgh so the wrapper can zero it, keeping the 28px for pages
that lay out their own children.

Hubs is a source you install from and a catalog you publish, not inventory
you own, so it no longer sits in the Library group next to Skills, Agents and
Plugins. The Skills page header already links to it and the page already
carries a back link there. Skills stays highlighted while the hub page is
open. Plugins takes the Package icon its own page identifies with, so the
sidebar no longer shows two identical puzzle pieces.

* fix(skill): stop implement-feature from running --no-tui as a command

The dispatch-order note wrote "not --no-tui" as !`--no-tui`. In a skill file
that is the syntax for running a shell command at load time, so the skill died
with "command not found: --no-tui" before any of it could be read. Spell the
condition out in words instead.

* feat(list): toggle model invocation for a skill with M

The only cheap gesture in the list TUI was E, which hides a skill from every
harness. Wanting a skill installed but not auto-loaded meant leaving the TUI
to edit SKILL.md, so people disabled skills they only meant to make
manual-only. M flips disable-model-invocation in place and the detail panel
shows a "manual only" badge so the state is never a blind toggle.

Unlike E this edits the skill file, which upstream may own: update skips
tracked repos with local changes, and reinstalling a skill drops the edit. M
says so and asks before writing in those cases. The flag is written as a
single-line edit rather than a YAML round-trip, and turning it back off
removes the line, so two presses return the file byte for byte and a tracked
repo is clean again. Agents are left alone; their harnesses do not read the key.

Refs #283

* feat(plugin): manage complete plugins across agent tools

Add CLI, TUI, and web flows for discovery, adoption, sync selection, updates, and removal while preserving native package formats and unrelated installations.

Support Claude, Codex, Cursor, Antigravity desktop, Pi, and OpenCode. Update help, completions, built-in skill, and documentation; keep plugins outside sync --all.

* docs(skill): describe the redesigned dashboard in the style skill

The style skill still documented the pre-redesign hand-drawn system, so
pages written with it came out on legacy tokens and outside the ss-*
classes; the new Plugins page was the first casualty.

The rewrite names tokens and classes and points to components.css for
their values, because copied values are what went stale last time. The
ui command docs described Playful by the old look as well.

* fix(ui): keep Playful ghost buttons free of stray shadows

The hover and disabled rules outranked the ghost variant's
box-shadow: none, so a frameless button grew a lone shadow arc in
Playful. Bulk toolbar and toast buttons shared the problem.

Ghost also gets a soft outline in Playful: beside 2px ink frames a bare
label such as Cancel did not read as a button.

* refactor(ui): lay out the Plugins page like the MCP page

The page was built on legacy tokens and plain markup, so it missed the
Playful frames and drifted from every other page. A per-agent column
layout would not have scaled either: each agent that gains plugin
support would add a column.

Plugins now follow the MCP server list: one row per plugin with its
agents as toggles inside the row, so the list only grows downwards.
Per-agent sync and update move to package-level actions in the row
menu, and the dialogs use the standard header, body and footer.

* feat(ui): give plugins a kind colour and per-agent actions

Plugins borrowed a neutral grey tile because no kind colour existed,
which made them the one resource without an identity on the page.
Magenta sits furthest from the five hues already taken.

Laying plugins out as rows had dropped the per-agent sync and update.
Retrying one agent after a partial failure should not re-run the rest,
so each agent in the expanded row gets its own menu. Update is left out
for a deselected agent, which has nothing installed to update.

* feat(ui): count plugins on the Dashboard

The source summary listed every resource kind except plugins, so the
Dashboard under-reported what a source holds. The Playful source note
grows to fit a fifth row.

MCP now sits above Plugins in the sidebar to match that order, and its
Dashboard label reuses the sidebar's "MCP" instead of a longer string
of its own.

* feat(scripts): add a host verification environment

Plugin and MCP work talks to the real Agent CLIs, and those live on the
host, not in the devcontainer, where every target reports "not installed".
Verifying by hand meant either pointing a build at real config or
assembling a dozen environment variables each time.

`make verify` builds a host binary and runs it against .verify-home/ in
the repo, redirecting HOME, the XDG dirs and each agent's own config
variable. The environment starts from `env -i`, so a stray
SKILLSHARE_CONFIG in the caller's shell cannot pull the run back to real
paths. Living inside the repo is safe because project-mode detection
only inspects the working directory and never walks up to a parent.

It also seeds the dashboard cache from ui/dist. A dev build serves a
placeholder rather than the working tree, because runtime download only
applies to numbered versions, so the UI was previously unverifiable
without a release.

* fix(ui): show progress while a plugin selection is applied

Toggling an agent shells out to that agent's own CLI, which takes
seconds. The row gave no sign of it: the toggle only greyed out, and
the confirmation badge is hidden while a target is deselected, so
turning one on looked like nothing happened at all.

The toggle being applied now lifts out of the greyed state and spins in
its badge. Agent versions also get room for their real strings, since
"2.1.276 (Claude Code)" was truncated to a width chosen for a bare
version number.

verify.sh gains a 'run' subcommand, so the same throwaway environment
can be driven from a script rather than only an interactive shell.

* fix(ui): spin the control that started a plugin action

Reading the inventory shells out to six agent CLIs and takes about two
and a half seconds, and every action refreshes it afterwards. Nothing on
the page said so: a menu action closed the menu and left the page still,
so the wait read as a freeze.

Each control now tracks its own work. Check, sync and import spin in
place, a menu action spins the row it acts on, and the agents refresh
follows the query itself rather than the mutation flag.

* feat(ui): split MCP add and import by where the configuration comes from

"Import from a target" opened a dialog whose second tab pasted a snippet,
which is not a target and usually comes from a provider's setup page rather
than a tool the user already configured. Pasting is a way to add a server,
so it moves under "Add server" beside the form, and importing now means one
thing: read what an installed Agent already has.

The paste side gains a file picker, matching `mcp import --file`; the API
only ever took content, so the browser reads the file and fills the editor.

The target picker no longer waits for a successful parse, and a footer that
said "writes 0 config files" next to a greyed-out button now names what is
missing instead.

* fix(ui): label the plugins result strip as the last action

The strip and the plugin inventory below it used the same list styling with
no heading on either, so two rows carrying the same plugin name read as one
list. The status word made it worse: "imported" is one of the outcomes
lifecycle.go returns for an action, but it sat where an inventory row shows
state, so it looked like a property of the plugin.

Give it the section heading the Agents list already has, plus a count and a
dismiss button, so it reads as the report it is.

* feat(plugins): expand compatibility and clarify setup guidance

Support additional native targets, safe source links, Git refs, and explicit OpenCode entries while exposing per-target capabilities across CLI, TUI, and UI.

Separate unsupported integrations from environment errors, explain next steps in plain language, and link official documentation. Update built-in guidance, website docs, completions, and regression coverage.

* feat(plugin): serve a plugin's files and translatable discovery problems

The dashboard could only show a plugin's name and targets, so reviewing
what a plugin ships meant opening the snapshot by hand. Files and
ReadFile expose the reviewed local copy read-only through os.OpenRoot,
which keeps reads inside the snapshot even across symlinks.

Discovery problems now carry a key and arguments next to the English
sentence, so the dashboard can translate them while the CLI keeps its
wording. Inventory asks every Agent CLI in parallel and Packages answers
from config alone, so the plugin list no longer waits on the slowest CLI.

* feat(mcp): sync to Pi, show native config, and lay out written entries

Pi has no built-in MCP support, so a server targeting it must name the
third-party extension that will read the file. `--pi-extension` and the
`piExtension` source field record that choice, and sync writes the file
format of the chosen package instead of guessing.

RenderNative and POST /api/mcp/render return what each Agent would
receive for a definition, with secrets kept as references, so the
dashboard can show the result before anything is written.

Sync used to insert entries on a single line and never revisit them. A
managed entry that still sits on one line is now reported as an update
and rewritten one field per line; entries formatted by hand are left
alone.

* feat(ui): choose plugin Agents like MCP, browse plugin files, view MCP config

The plugin fold listed bound Agents with a per-Agent menu, while MCP let
you simply tick the Agents you want. Plugins now work the same way: the
fold discovers where the source can also go, shows those Agents as
unticked toggles, and a tick previews an install. The per-Agent menu is
gone, and updating a plugin targets only the Agents that support it
instead of hiding the action when one of them does not.

A plugin with a local copy can be browsed in a read-only files dialog,
using the same tree as a skill's Files tab. The MCP "view config" moved
out of a fold in the server form into its own view, reachable from the
server menu, so the native result has room to be read. The MCP dialogs
also ask for the Pi extension when Pi is selected.

Playful tile names drop from 25px to 22px: "brainstorming" was 1px wider
than the tile and lost its last letter to the next line.

* docs: reshoot dashboard screenshots for the redesigned UI

The README and website still showed the pre-redesign dashboard, which no longer matches what users see after upgrading.

* docs: describe MCP, plugins and the new dashboard for v0.21.0

The README still announced v0.20.0 and never mentioned plugins, and its
MCP section listed four clients. The built-in skill and the docs pick up
the Pi extension setup, the formatting-only MCP update, and the plugin
fold and files dialog, so agents and users are not surprised by them.
2026-09-19 03:14:03 +08:00
Willie f52ae74c5f feat(audit): remember findings accepted via --force across updates
Overriding the audit gate with --force was per-invocation, so skills that
legitimately quote attack strings (security scanners, red-team docs) had to
be forced on every `update --all`. The only alternative, disabling the rule,
was global and turned it off for every skill.

Record the accepted findings (rule + file + matched text, no line number) in
.metadata.json under `audit_accepted`, keyed by skill relPath so it survives
entry rewrites and works for tracked repos. Later updates mark matching
findings as acknowledged and exclude them from the block decision; any new
finding, or the same rule matching different text, still blocks.

Staged installs audit a temp directory, so InstallOptions gains an
AuditAcceptRoot/AuditAcceptPath override pointing at the final destination.

Refs #279
2026-09-17 10:24:18 +08:00
Rusty ShacklefordandWillie 60e19f96d5 feat(project): support a visible skillshare/ project directory (#256) (#258)
* fix(project): refuse to re-init a project that lost its config.yaml

Every project-mode command auto-initializes when .skillshare/config.yaml
is missing. That is right for a repository with no project directory at
all, and for the shared skills repo produced by 'init -p --config local',
which gitignores config.yaml so each developer regenerates their own.

It was wrong for the case in between. A .skillshare/ that already held
skills or agents, whose config.yaml was simply gone, was re-initialized
into an empty config. Every configured target was dropped, the target
symlinks were left behind pointing at a project the config no longer
described, and the command exited 0. Nothing said anything had happened.

Add ensureProjectConfig, which replaces the open-coded auto-init at every
project command entry point. It initializes as before when there is no
project directory, and when config.yaml is gitignored, so both intentional
cases keep working untouched. When the directory holds skills or agents
and its config is neither present nor gitignored, it now returns an error
pointing at version control or an explicit 'skillshare init -p' instead of
writing over the project.

The gitignore check is treated as inconclusive on error, so a repository
that cannot be inspected is guarded rather than overwritten.

* feat(project): support a visible skillshare/ project directory

Project mode is identified only by .skillshare/config.yaml, and trash,
backups, logs and audit-rules.yaml anchor to that same hidden directory.
The sources option (#153) made project content relocatable, but the
marker and operational state stay hidden, so repositories that treat
skills as reviewable content still carry a hidden directory whose only
job is to hold config.yaml.

Resolve the project directory through a new leaf package that checks
.skillshare/config.yaml first and skillshare/config.yaml second, and
derive every config, state, source-default and gitignore path from the
result. The hidden name wins whenever both exist, so an existing project
never moves and no migration is needed. The package imports nothing else
internal because internal/audit cannot import internal/config without a
cycle.

Add init -p --visible to create the visible layout. Default init -p
behaviour and output are unchanged.

Two ambiguities the visible name introduces:

- The global config directory is also called skillshare
  (<config-home>/skillshare), so the two places that infer scope from a
  config path now exclude the global location by full path rather than
  by directory name. TestLogDir_Global asserted a fixture path without
  declaring a config home, which hid this; it now sets XDG_CONFIG_HOME.
- An unrelated directory named skillshare/ must not be adopted as a
  partially initialized project, so the visible name is only claimed
  when it carries a marker of its own: a skills/ or agents/ directory,
  or a .gitignore that ignores config.yaml.

The missing-config guard added in the previous commit is generalized to
resolve through the new package, so it covers both layouts. The
gitignored-config marker matters there too. A repository shared by
'init -p --visible --config local' before any skill was committed clones
with nothing but that .gitignore, because git drops the empty skills/
and agents/ directories; recognizing it keeps the repair pointed at the
visible directory instead of writing a hidden one beside it.

Refs #256

* fix(project): reconcile visible directory support with main

Consolidate the missing-config guard and regression tests already merged in #260. Preserve both directory layouts and document and test resyncing target links after a rename. Follow-up for #258.

---------

Co-authored-by: Willie <egg358358@gmail.com>
2026-09-05 12:07:00 +08:00
Willie e780fbf1ab fix(sync): honour agent frontmatter targets when syncing agents
The agent discovery already parsed the `targets` frontmatter list into
DiscoveredResource.Targets, but no agent sync path ever applied it, so an
agent declared for one tool was still delivered to every agent-capable
target. Agents have no shared schema across harnesses, so this gives authors
a way to keep a per-tool variant of the same agent without cross-polluting
targets. Applied in CLI sync (global and project), the dashboard sync
handler, doctor's expected count and the target summary so all views agree.

Refs #267
2026-09-02 13:36:30 +08:00
Willie 43edd3ee1c docs: mention Windows drive-letter paths in local path formats 2026-09-02 13:08:40 +08:00
Willie 0a3e669b09 fix(audit): decouple audit override from Force so --force reaches the gate
InstallOptions.Force carried two meanings: "overwrite what is already
there" and "proceed despite audit findings". Update paths set Force
unconditionally to overwrite a staged temp dir, so they had to leave it
off to keep the audit gate alive -- which swallowed the caller's --force
and made the gate impossible to override from either the CLI or the web
UI.

Split the audit intent into InstallOptions.AuditOverride and route every
gate through it alone. Entry points translate --force explicitly, so a
missed one degrades to "force has no effect" rather than "audit is
bypassed". Scan failures stay fail-closed regardless: accepting known
findings is not the same as being unable to learn any.

This also closes two paths that bypassed the gate outright, since both
inherited Force for overwrite reasons alone: install --json and grouped
batch updates.

In the web UI, Force Retry now appears only on failures force can
actually resolve -- a permission-denied unlink previously offered a
button that could never succeed -- and CLI-only flag hints are stripped
from messages rendered there.

Behaviour change: a --force at install time no longer exempts later
updates from the audit gate; it is a one-off decision per command.
2026-08-27 17:10:29 +08:00
Willie 9c0200ab2c fix(doctor): make symlink compatibility hint deterministic
The hint picked its example target by ranging a map, so the same config
produced a different suggestion on each run, and it could name a target
whose runtime handles symlinks fine — telling users to change something
that was not broken. Restrict the choice to the targets known to skip
symlinked skill directories, in the documented priority order.

Also correct the sync docs: the hint is printed by doctor, not sync.
2026-08-02 22:39:00 +08:00
Willie 9143b467e0 fix(targets): split gemini out of antigravity and correct global path
Antigravity and Gemini CLI read different global skill directories, so
folding gemini into antigravity as an alias made one of them wrong for
every user. Antigravity loads ~/.gemini/config/skills; Gemini CLI loads
~/.gemini/skills. Restore gemini as its own target so both resolve
correctly.

Also document that Antigravity's skill scanner skips symlinks entirely
(surfacing as "Incorrect function" on Windows, silent absence elsewhere)
along with the two available workarounds.

Closes #255
2026-08-02 22:38:56 +08:00
Willie 262da080c0 docs(backup): document backup scope and disk space, fix stale paths
The backup docs claimed per-skill symlinks were "resolved and followed" and
their real content backed up, which is now the opposite of what happens.

Adds a Backups & Disk Space section contrasting the three mechanisms that are
easy to conflate — .gitignore (git only), ignore: (sync), and backup (local
target content) — plus an ENOSPC troubleshooting entry, since disk space had
no coverage anywhere in troubleshooting despite being how this surfaced.

Also corrects two long-standing errors: the backup location was documented
under ~/.config in the built-in skill reference and in a `backup --list`
example, but backups live in the XDG data dir (config.DataDir()); and the
built-in skill claimed backup was global-mode only, when project mode does
support agent backups.

Refs #252
2026-07-30 00:55:47 +08:00
Willie a1e22a7e36 feat(list): add --status filter for non-interactive views
The enabled/disabled filter existed only inside the list TUI (`s` key,
`status:` search tag), so scripts had no way to ask for one status. They
had to know that `disabled` is omitted for enabled entries and filter the
JSON themselves; plain-text callers had to parse the `[disabled]` label.

`--status all|enabled|disabled` exposes the same concept outside the TUI.
`all` is normalized to an empty filter at parse time, which keeps the
default output, the JSON array shape, and the tracked-repositories summary
byte-identical to omitting the flag. Status combines with the pattern and
--type using AND semantics, and works in project mode and for agents.

The TUI still loads both enabled and disabled entries; --status only seeds
the initial `Status:` chip, so `s` can cycle back to All.

Implements proposals/244-list-status-filter.md.
Closes #244
2026-07-29 23:23:24 +08:00
Willie ba46ae8a77 feat(targets): add grok as a built-in target
xAI's Grok CLI reads skills from ~/.grok/skills (global) and
.grok/skills (project), with legacy fallback to ~/.agents/skills.

Ref: https://docs.x.ai/build/features/skills-plugins-marketplaces
2026-07-16 09:30:51 +08:00
Willie e818a29cad fix(collect): preserve overwrite guard in JSON mode
--json implied --force, silently overwriting existing skills/agents
in source when collecting. Decouple confirmation-skip from the
overwrite guard, same fix as PR #243 for uninstall.
2026-07-15 09:42:47 +08:00
hhh2210 c5f876c79e fix(uninstall): preserve dirty-repo guard in JSON mode 2026-07-15 09:30:54 +08:00
Willie 54ae7b04e2 fix(install): reject project-root self-install via web UI
The project-root self-install guard lived only in the CLI handler, so the
web UI could still copy the project root into its own .skillshare/skills/
subtree in project mode. Extract the check into a shared
install.RejectProjectRootLocalInstall and apply it in handleInstall and
handleInstallBatch, returning 400 with the same guidance.

Also restructure the rejection message into a cause line plus an
actionable "Run '...'" hint, matching the project's error convention.
2026-06-16 10:04:57 +08:00
Willie 3ad54abb6e chore: release v0.20.13 2026-06-11 16:15:25 +08:00
Willie 060886c281 chore: release v0.20.12 2026-06-11 01:18:10 +08:00
Willie 10d94a3542 fix: suggest install for missing tracked repos 2026-06-10 15:54:23 +08:00
Willie 63adb16bbb docs: document disabling skills by folder glob
Surface the existing .skillignore glob support in the enable/disable
command reference and the folder-organization guide. Users reported
(issue #209) only finding it buried in reference/filtering, assuming
disable accepted skill names only.

Add "frontend/**" folder examples, a dedicated "Disable a Whole Folder"
section, and shell-quoting guidance.
2026-06-09 12:44:30 +08:00
Willie e4ba03334a chore: release v0.20.8 2026-06-05 13:56:07 +08:00
Willie ccbe941291 feat: add Zed editor target
Zed added agent-skills support in vercel-labs/skills v1.5.8, using the
universal ~/.agents/skills (global) and .agents/skills (project) paths with
a flat-only skill layout. Register it as a built-in target and document it.

Since Zed shares the universal .agents/skills project path, it is auto-grouped
under the universal target by GroupedProjectTargets(); the docs note reflects
this. Verified in devcontainer: internal/config tests pass and zed resolves
via KnownTargetNames().
2026-06-03 00:21:29 +08:00
Willie b0732b75bb docs(extras): document --add-target/--remove-target; drop 'extras mode' subcommand 2026-06-02 17:22:56 +08:00
Willie 1d0ee69955 feat: support SSH hub sources for private and GHE hosts
Hub index fetch previously handled only unauthenticated HTTP(S) GET or
local file paths, leaving private and GitHub Enterprise repos out of
reach — raw HTTPS URLs redirect to login before token headers apply, and
SSH-style hub URLs were unrecognized.

Resolve SSH hub sources by shallow-cloning the repo with the user's SSH
keys and reading the index from it. The in-repo index path uses the
existing //path subdir convention (consistent with `install`), defaulting
to skillshare-hub.json at the repo root. Both scp-style and ssh:// URLs
are accepted. In the web dashboard, SSH clones are restricted to saved
hubs so a request-supplied URL can't drive an arbitrary clone.

Ref #185
2026-06-02 16:29:25 +08:00
Willie 594a767734 chore: release v0.20.3 2026-06-01 16:31:13 +08:00
Willie 85cc972f95 docs(doctor): document suggestions field; refine remediation wording
Follow-up to eb99118d (doctor overlap suggestions):

- Document the optional `suggestions` JSON field in doctor.md with an example

- Clarify shared-paths wording: the listed targets are all current collisions, not "the others"

- Print the cross-target suggestion after overlap detail lines for a more natural read order
2026-05-31 20:56:37 +08:00
Willie 1183e0a366 fix: improve codex agent extension validation 2026-05-31 13:39:41 +08:00
Letiancheng Lee ad9ffde242 fix codex agent extension validation 2026-05-31 13:07:25 +08:00
Willie 314e2b2df4 feat(init): switch git_root scope headlessly on an existing setup
Previously 'skillshare init --git-root <scope>' on an already-initialized
setup either errored with 'already initialized' (no --remote) or warned and
ignored the flag (with --remote), so there was no non-interactive way to
change the scope after init — only the web UI or a manual config edit.

handleExistingInit now treats 'init --git-root <scope>' (without --remote) as
a headless scope switch via switchGitRootScope: it inits a repo at the new
scope directory (reusing one already there, sharing doGitInitIfAbsent with the
fresh-init and server paths) and persists git_root. It does not relocate an
existing repo — switching scope means 'version a different directory', not
'move history'. Combined with --remote the flag still falls through to the
remote path, now pointing users at the standalone form instead of a bare
'ignored' warning.

Update the mismatch guidance to offer 'skillshare init --git-root <scope>' as
the first fix, and revise the git_root docs (configuration + init) to document
the headless switch, superseding the earlier 'must re-run init / not supported'
wording. Add TestGitRoot_SwitchScopeAfterInit.
2026-05-30 19:23:12 +08:00
Willie 9fb7b1eca4 docs(git-root): clarify how to change scope after init; fix misleading mismatch guidance
The mismatch guidance told users to re-run 'skillshare init', but init warns
and ignores --git-root once a repo already exists, so it never relocates the
repo. Reword the CLI message to state the real options: run 'git init' at the
new scope dir for a fresh history, or 'mv <old>/.git <new>/.git' to keep
history, or set git_root to match the existing repo.

Add a 'Changing the scope after init' section to the git_root config reference
and point the commit/push/pull pages at it, replacing the same misleading
're-run init' phrasing.
2026-05-30 19:23:12 +08:00
Willie 32fd08c692 feat(list): filter skills by enabled/disabled status in list TUI
Large skill lists made it hard to spot which skills are disabled via
.skillignore. Add a status filter to `skillshare list`: press `s` to
cycle the All -> Enabled -> Disabled view, shown as a `Status:` chip
beside the tab bar. The `s:enabled` / `s:disabled` filter token is also
supported for combining status with other tags (e.g. `t:tracked
s:disabled`). Toggling a skill's state while a status filter is active
re-applies the filter so it leaves the view.

Closes #172
2026-05-30 19:23:12 +08:00
Willie f59d5e905b refactor(extensions): simplify reference converters 2026-05-30 19:23:12 +08:00
Willie bb0f3c2a0b docs(extras): correct list output and document transform conflict safety
- Fix the `extras list` plain-text example to match current output: real
  header/separator, `✓` icons, no trailing "synced" word on synced rows, and
  an extension target labeled `extension: <name>`.
- Note the per-target `extension` field in `--json` output.
- Document the transform overwrite-safety contract (symlink auto-replace;
  regular file/directory skipped without --force; --force replaces a
  conflicting directory wholesale).
- Add a one-line pointer to transform extensions in the built-in skill.
2026-05-30 19:23:12 +08:00
Willie fcbfd39be2 refactor(extensions): describe and rename built-ins by output
md2codex / md2gemini named the *input* (markdown) and read poorly. Rename
the bundled extensions after what they produce: codex-agents and
gemini-commands. Turn the BuiltinExtensions catalog into structs carrying
a human-readable description so the dashboard can explain each one before
install, and propagate the new names across tests and docs.
2026-05-30 19:23:12 +08:00
Willie c0609011e4 feat(extensions): map model field and document Codex agents recipe
The md2codex reference converter now carries the agent's `model`
frontmatter into the generated TOML, matching what Codex agents expect.
Document the extras + extension recipe for converting markdown agents to
Codex TOML so the conversion works without a built-in agents target.
2026-05-30 19:23:12 +08:00
Willie 9e4563d143 chore(extensions): port reference scripts to Node.js and validate extras extension schema
Port the md2gemini and md2codex reference extensions from Python to
Node.js for broader portability (Node ships uniformly across Windows,
macOS, and Linux). Add the extension field to extraTargetConfig in the
global and project JSON schemas so editors accept it, with a schema test
guarding its presence.
2026-05-30 19:23:12 +08:00
Willie 5c3a3dff30 docs: document extras extension transforms 2026-05-30 19:23:12 +08:00
Willie 7941ef295a docs: document git_root scope and --git-root flag 2026-05-30 19:23:12 +08:00
Willie d32a15fd94 chore: release v0.19.24 2026-05-27 17:03:13 +08:00
Willie a2f958d288 feat(ui): background mode, in-place upgrade, and PWA support
Three user-visible additions to the web dashboard, plus the CLI surface
needed to drive them.

* `skillshare ui start` / `skillshare ui stop` — run the dashboard as a
  managed background process. Re-running start reuses the existing
  healthy process; stop uses the remembered host/port. Foreground
  `skillshare ui` keeps working unchanged. Process tracking lives in
  ui_process_{unix,windows,other}.go via a PID + current-state file.
* `--app` — opens the dashboard in a Chromium app-mode window (Chrome,
  Edge, Brave) on macOS, Windows, and Linux for a separate Dock/taskbar
  entry without browser chrome.
* In-place upgrade from the browser — the Update dialog and the Doctor
  page's Version card now expose an Update now button. Backed by two
  new endpoints (POST /api/upgrade, POST /api/restart in
  handler_restart_upgrade.go); the browser polls GET /api/health and
  reloads once the new server is ready. Dev builds short-circuit with
  `devMode: true` and a simulated restart so the flow can be exercised
  without rebuilding the binary.
* Progressive Web App — site.webmanifest, app icons (192/512), and a
  minimal service worker registered from main.tsx. Supporting browsers
  can install the dashboard as a standalone desktop app.
* Doctor Version card redesign — state-coloured icon (blue when an
  update is available, green when up to date), explicit
  `current → latest` delta, Update button only when there is something
  to upgrade.
* i18n — translate "DEV mode" in zh-TW / zh-CN / ko (previously left
  as raw English).

Adds CHANGELOG.md and website changelog entries for v0.19.20 and
refreshes website/docs/reference/commands/ui.md to document the new
modes, --app flag, new REST endpoints, and the in-place upgrade flow.
2026-05-24 01:21:06 +08:00
Willie 37819bf76b docs: v0.19.17 changelog + doctor path overlap section
- CHANGELOG entry covering doctor warnings, sync hint, and cline path fix
- doctor.md: new "Path Overlap" section documenting shared_target_paths
  and cross_target_discovery checks with example output and resolutions
2026-05-22 01:00:59 +08:00
Willie f01a679c56 fix(targets): revert cline paths to brand-specific dirs
Cline's official docs (docs.cline.bot/features/skills) list only
.cline/skills (project) and ~/.cline/skills (global) as supported skill
directories. The previous change to ~/.agents/skills was based on the
incorrect assumption that Cline scans the universal .agents/skills path,
which it does not.

Restore cline paths to:
  - global:  ~/.cline/skills
  - project: .cline/skills

Also remove cline from the universal-grouping sentence in the website
target reference, since cline no longer shares the .agents/skills root.

Existing users with cline enabled should manually remove stale cline
entries under ~/.agents/skills after upgrading.
2026-05-21 23:18:27 +08:00
Willie 3b9cb44be6 chore: release v0.19.14 2026-05-20 14:07:51 +08:00
Willie 3b2f062cf0 docs: add v0.19.11 changelog, preserve_tilde_on_save docs, fix CI test
- Add changelog entry for v0.19.11 (preserve_tilde_on_save, backups gitignore)
- Document preserve_tilde_on_save in configuration reference, cross-machine sync, FAQ
- Fix TestFoldHomePath/unrelated-abs: use /opt/unrelated/foo instead of /tmp/foo (CI sets HOME=/tmp)
- Add iFwu to README contributors
2026-05-14 13:22:23 +08:00
Willie 1acfd4b9fe docs: add --quiet flag to sync flags table and context_cost to JSON example
Also documents context_budget config block in configuration reference
with field types, defaults, and cross-link to sync docs.
2026-05-11 21:34:38 +08:00
Willie b1c29c5c9d docs: document context budget warnings and --quiet flag 2026-05-11 21:34:38 +08:00
Willie 084cc01792 docs: add completion command documentation (#148)
- New website/docs/reference/commands/completion.md page
- Update commands index with completion entry
- Update quick-reference with completion shortcut
- Add shell completion to README highlights
2026-05-08 16:01:16 +08:00
Willie e48a301623 feat: add azure_hosts config for Azure DevOps Server on-premises
Add azure_hosts config parameter (analogous to gitlab_hosts) that allows
users to register self-hosted Azure DevOps Server hostnames so they
receive proper URL parsing without appending .git to clone URLs.

- Add AzureHosts field to Config and ProjectConfig structs
- Add SKILLSHARE_AZURE_HOSTS env var support with merge semantics
- Generalize hostname validation into shared normalizeHostList/mergeHostsFromEnv
- Add azureOnPremPattern regex and parseAzureOnPrem for /_git/ URL routing
- Add isAzureHost for config-based host detection (no auto-detect)
- Update TrackName to handle on-prem Azure DevOps clone URLs
- Wire AzureHosts through InstallContext, ParseOptions, and Server
- Add JSON Schema, UI fieldDocs, and website documentation
- Add 19 new tests covering config, source parsing, and server

Closes #147
2026-05-05 18:33:07 +08:00
Willie 57b0649d20 feat(targets): add 8 new agent targets and update cursor project path
Add AiderDesk, CodeArts Agent (Huawei), Code Studio (Syncfusion),
Devin for Terminal (Cognition), Dexto, ForgeCode, Rovo Dev (Atlassian),
and Tabnine CLI as built-in targets (56 → 64).

Update Cursor's project-level skill path from .cursor/skills to
.agents/skills to match Cursor's official documentation, which now
lists both paths as supported with .agents/skills as the ecosystem
standard convention. Global path (~/.cursor/skills) and agents paths
are unchanged.

All paths verified against official documentation or source code.
Codemaker excluded — no official docs confirm SKILL.md support.
2026-05-05 11:55:26 +08:00
Willie 806045d392 docs(agents): expand docs + skillshare SKILL.md for agent workflows
- skills/skillshare/SKILL.md: mention agents commands/flags in description
- website: document agents source dir, agent backup/restore, ignores,
  file structure, config fields, and project-mode agent rules
2026-04-11 00:41:29 +08:00
Willie 788f9bc6e9 feat(agents): JSON output + audit gate for install/update
Extend install/update with agent-aware --json output and apply the same
audit block-threshold gate skills already use.

Install:
- install --json: imply --force; imply --all only when neither
  --skill nor --agent is set (so explicit selectors still work)
- project-mode install now routes through cmdInstallProjectParsed
  so --json suppresses UI and emits a pure-JSON payload
- agent installs propagate SourceDir so metadata lands in the
  agents root, not the install subdir
- validation error lists --agent / --kind / --branch explicitly

Update agents:
- update agents supports --force, --skip-audit, --audit-threshold
- tracked agent repos + metadata-backed single-file agents now run
  the same audit gate as skills; blocks roll back from a temp stage
- JSON output returns the final per-agent status
  (updated/skipped/failed/up_to_date/...) by merging check results
  with batch update outcomes

Audit:
- auditInstalledAgent shares one helper with auditInstalledSkill
  (scan + cleanup callbacks); single-file agent scans now use
  audit.ScanFile / ScanFileForProject instead of staging the file
  into a temp directory
- UpdateAgentFromDiscovery stages to temp, audits, then renames
  atomically (rename already overwrites on POSIX)

Refactors pulled in while reworking these paths:
- extract jsonUISuppressor helper in json_output.go and use it
  from install/update/update_agents; collapses 4 copies of the
  suppress/restore closure dance and the per-error failJSON block
- drop relPath plumbing from installAgentFromDiscoveryInternal
  now that ScanFile doesn't need a staged relative path
- list.go render functions now use theme.ANSI() so NO_COLOR is
  respected in plain-text output

Tests:
- add TestInstallAgentFromDiscovery_HighFindingBlocked (unit)
- add TestUpdate_Agents_HighFindingBlockedByThreshold (integration)
- add TestInstall_Project_JSON_Agent_PureJSON,
  TestUpdate_Agents_JSON_ReportsFinalStatus
- fix TestList_SKILLSHARE_THEME_Light / TestList_NO_COLOR to
  write a config before invoking list
- fix TestTargetList_NoTUI_FallsBackToPlainText assertion to match
  the new structured Mode: merge output
- fix TestDoctor_AllGood_PassesAll by pinning SKILLSHARE_THEME=dark
  so the no-TTY theme fallback warning doesn't fire
- add list_tui_content_test.go covering light/dark glamour base
- list detail pane now picks LightStyleConfig on light terminals

Docs:
- update install.md, update.md, understand/agents.md for the new
  flags, JSON shapes, and agents update workflow
2026-04-10 23:27:26 +08:00
Willie d4bd0a66df docs(sync,diff): fix agent sync description and add agent diff section
- Fix sync.md: 'sync' defaults to skills only, not skills+agents
- Fix --all flag description: syncs skills + agents + extras
- Add 'sync agents' to usage examples
- Add Agent Diff section to diff.md with usage examples
2026-04-09 23:56:03 +08:00