Commit Graph
2287 Commits
Author SHA1 Message Date
Willie 63affe976e feat(website): promote the desktop app as the primary entry point
Make the desktop app visible in the homepage, navigation, and README before CLI installation. Add localized installation guides and promotion copy across all five documentation languages, with Homebrew as the recommended macOS path.
2026-10-01 11:14:28 +08:00
Willie 6fbb5e109b feat(ui): add Git Sync discard changes
Let users discard uncommitted source changes after confirmation, with dry-run support. Restore tracked files to HEAD and remove untracked files while preserving ignored files, nested repositories, and root-scope config.yaml.

Guard against ancestor repositories and repositories without a first commit. Cover the API and confirmation flow with regression tests and sync all UI locales and Git Sync documentation.
2026-10-01 10:17:47 +08:00
Willie abd1b49f37 docs: update README latest highlights for v0.23.0
Replace the outdated v0.21 announcement with hooks, MCP tool policy, and dashboard highlights. Keep all four translated READMEs aligned with the English source.
2026-10-01 03:18:42 +08:00
Willie de7525c34d chore: release v0.23.0 v0.23.0 2026-10-01 02:31:36 +08:00
Willie ef38ac89ad docs(changelog): say what install.sh does with an older binary
The 0.23.0 entry claimed an existing installation is upgraded in place, but
the installer always writes to ~/.local/bin unless INSTALL_DIR is set and
only warns when an older copy, such as /usr/local/bin/skillshare, comes
first on PATH. Users upgrading would keep running the old binary.
2026-10-01 02:31:36 +08:00
Willie c327a26e30 feat: native hooks, MCP tool policy and Pi built-in MCP (v0.23.0) (#304)
* feat(hooks): manage native hooks across agents

Add global and project hook management for ten coding agents with native
format adapters, explicit ownership, revision-guarded synchronization and
selective backup/restore. Preserve unrelated native configuration and leave
hook execution and trust decisions with each agent.

Expose CLI commands and completions alongside dashboard import, editing,
native preview, target/project views, synchronization and backups. Localize
messages and document the workflows across supported locales.

Validation: devcontainer make check, full dashboard Vitest suite,
TypeScript/Vite build, scoped ESLint, isolated CLI lifecycle and real UI
acceptance. Native agent hook execution was not tested.

* feat(mcp)!: sync Pi only through its built-in MCP

Pi could be synced through three different mechanisms (built-in MCP,
pi-mcp-adapter, or the extension file), chosen per server. Mixing them
inside one scope was an error users hit easily, and the adapter and
extension files drifted from what Pi itself reads. Pi's built-in MCP
now covers what the other modes offered, so every Pi server is written
to ~/.pi/agent/mcp.json or <project>/.pi/mcp.json.

Existing setups migrate on the next sync: entries Skillshare wrote to
mcp-adapter.json are removed through the ownership ledger, extension
entries are rewritten in place, and hand-written entries stay put.
piExtension and piOptionsPrune still load (with a notice) so old
configs keep working, and are dropped on the next save. directTools is
kept but no longer rendered, since only the adapter reads it.

Pruning unchanged fields Skillshare wrote earlier is now always on,
the per-project off switch no longer applies to Pi, and the removed
--pi-extension and --pi-options-prune flags explain the change instead
of failing as unknown. Import still reads mcp-adapter.json read-only so
servers kept only there can be brought over.

BREAKING CHANGE: --pi-extension and --pi-options-prune were removed;
Pi servers are always synced to Pi's built-in MCP file.

* fix(mcp): load Pi switches and adapter options left from before 0.23.0

Phase 1 made Pi sync only through its built-in MCP, which left two
upgrade paths broken or misleading:

- A project entry with disabled: true that selected Pi used to work in
  adapter mode, but now fails every sync with "pi cannot turn off".
  Loading now takes pi (and Pi accounts) out of such an entry with a
  notice; an entry left with no targets stays and turns nothing off, so
  an explicit empty list is now valid for a switch. Saving a new switch
  for pi still fails.
- piOptions keys that only pi-mcp-adapter reads (lifecycle, idleTimeout,
  approveTools, ...) were copied into Pi's built-in mcp.json, where
  nothing reads them. Loading drops them with a notice naming each key,
  and saving new ones is refused. Keys neither Pi nor the adapter
  documents still pass through. includeTools/excludeTools are left for
  the tool policy change, which converts them.

Both changes rewrite the YAML node on load, like the phase 1 legacy
fields, so the next save persists them.

* feat(mcp): portable tool policy per server

Users need one place to say which of a server's tools the model sees,
instead of Pi-only adapter options that Pi's built-in MCP no longer
reads. A server's tools{expose, allow, deny} is rendered per Agent:
Pi gets exposure and an ordered toolExposure, Codex gets
enabled_tools/disabled_tools, Copilot gets its tools list. Parts an
Agent cannot hold (OpenCode and Kilo have no per-server field) are
named in the plan and by mcp check rather than dropped silently.

directTools and the adapter's includeTools/excludeTools are converted
on load and on import, so existing configs keep their behavior; the
--direct-tools flag is removed with a pointer to the new flags.
check --live now reports tool names so the dashboard can suggest them.

Refs #140

* feat(ui): drop the Pi mode, prune switch and Direct tools from MCP

Since 0.23.0 Pi syncs only through its built-in MCP and the API no longer
returns piExtension, so the server dialog showed an empty "Pi MCP mode"
select, links to pi-mcp-adapter and pi-mcp-extension, a prune switch the
backend ignores and adapter-only Direct tools. Toggling Pi also opened a
mode setup that no longer exists, and Pi was still offered as an Agent
that can turn a global server off per project, which the backend refuses.

Pi now shows only tool exposure, its other settings and one link to
Pi's MCP docs. The import dialog still sends piExtension, but only to
pick between Pi's mcp.json and the legacy mcp-adapter.json, which the
listed path already tells apart. Settings the config still carries from
before 0.23.0 are explained once on the MCP page from the source's
notices, worded in the dashboard's language.

* fix(ui): clarify hook takeover and localize MCP actions

Identify global and project hooks in sync previews, show full takeover guidance, and link project conflicts to their Hooks tab. Translate MCP pending actions using the existing locale keys.

* feat(mcp): name unapplied tool policy parts in the render preview

The dashboard's server editor needs to say which Agents cannot follow
part of a tool policy before the server is saved. The plan's notices
only cover saved servers, so each rendered target now carries the gaps
from toolPolicyGaps instead of the UI re-implementing the per-Agent rules.

Refs #140

* feat(ui): edit the portable MCP tool policy in the dashboard

Saving a server from the edit dialog rebuilt it from the form and
dropped its tools policy. The draft now carries tools, and a Tools
section edits exposure, allow and deny for every Agent at once. Tool
names can be loaded on demand from the saved server through the live
check, and each selected Agent that does not apply a part is named from
the backend's render preview.

Pi's other settings flag the adapter-only keys and the exposure fields
that Tools now owns, so the form refuses what the backend refuses with
a message that points to Tools. Rows show a short policy marker, and the
plan's tool policy notices are localized on the MCP page.

Refs #140

* feat(mcp): save the config without retired settings on sync

Notices about settings 0.23.0 retired (piExtension, piOptionsPrune,
adapter-only piOptions, Pi switch entries, directTools/includeTools/
excludeTools) only went away when the user happened to save MCP settings.
Sync never rewrote the source, so most users kept seeing them.

Loading already converts those settings in memory, so a sync now writes
the converted config back (global, per project, external source, CLI and
dashboard), after keeping the previous content in the file history.
Dry runs write nothing, and a failed save is reported after the Agent
files are applied. The plan carries `migrates`, so the dashboard's sync
runs MCP even when no Agent file changes.

The CLI notices are one short line per kind with each server named
once, and a sync prints the file it updated with its backup. The
dashboard no longer shows these notices: sync handles them with nothing
for the user to do, and tool policy gaps stay in the server dialog.

* fix(ui): catch MCP tool policy mistakes before saving

The empty "Other Pi settings" box showed a toolExposure example even
while Tools had a setting. That example is exactly what the dialog
refuses in that state, so it read as a saved value that went unflagged.
The example now leaves toolExposure out while Tools is set.

A Deny list that removes every tool Allow keeps was only refused by the
server, in English with raw field names. The Tools section now says so
in the user's language and disables Save; the server check stays.

* fix(ui): move Pi settings help into info tooltips

The Pi block stacked four lines of help under the exposure select, one
of them in raw config words (entry, toolExposure), which pushed the
fields apart. The help now sits behind keyboard-focusable info icons:
one on a new "Pi settings" heading, which keeps the official docs link
beside it since a tooltip cannot hold a link, and one on the exposure
label with a shorter, plain explanation. The line saying Tools sets the
exposure stays, because it explains why the select is locked.

* docs(mcp): describe Pi built-in only and the tool policy

0.23.0 dropped the Pi modes, the prune switch and directTools, and added a
portable tools policy (#140, #143). The MCP reference still told users to
pick pi-mcp-adapter and pass flags that now fail, and said nothing about
what the first sync does to an old config or which Agents apply which part
of a tool policy.

The reference now covers the tools field and flags with a per-Agent table
linked to each Agent's docs, the dashboard Tools section, Pi's built-in
files and options, and an upgrade section: what the first sync converts,
which adapter entries it removes, the config save with its migrate backup,
and what replaces each removed flag. The how-to, dashboard and backup pages
follow.

* docs(skill): teach the built-in skill the Pi and tool policy changes

Agents using the skill would still pass --pi-extension and --direct-tools,
which fail since 0.23.0, and would not know the tools policy or what a sync
does to a 0.22 Pi config. The MCP reference now matches the CLI; the
description is unchanged and stays within its size limit.

* test(mcp): cover Pi migration and the tool policy in the runbook

The runbook still exercised pi-mcp-extension, pi-mcp-adapter and
--pi-options-prune, all removed in 0.23.0. New steps check Pi built-in
cleanup, the first-sync conversion of a 0.22 config with its migrate
backup and untouched hand-written adapter entries, the removed-flag
messages, and what each Agent receives from one tool policy.

* docs(wiki): record the 0.23.0 MCP Pi and tool policy milestone

Keeps the design decisions and evidence limits of #140 and #143 (the
ledger-driven migration, the migrate backup, per-Agent translation rules)
where later work can find them without reading five phase reports.

* docs(i18n): mirror the Pi built-in and tool policy docs in four locales

The zh-Hant, zh-Hans, ja and ko MCP pages still described the removed Pi
modes and flags, and linked to anchors that no longer exist in English.
They now carry the tool policy, Pi, and upgrade sections with the English
anchors and dashboard labels taken from each locale's UI strings.

* feat(mcp): probe an unsaved server definition for the dashboard

Loading tools in the server dialog could only probe the saved config, so
editing a URL and clicking load tested the old address and surfaced a raw
"connection refused" for a server the user was already fixing. A new server
could not load tools at all until saved.

POST /api/mcp/probe runs the existing live probe on the definition in the
request, resolving env and header references as the saved-server check does,
and never saves or syncs. Failures carry an error kind (connect, timeout,
auth, protocol, command, unknown) so the dashboard can explain them in the
user's language and keep the raw text as detail.

* fix(ui): load MCP tools with the dialog's current settings

The Tools section now probes the connection as the form describes it, so
an edited URL or command is what gets tested and a new server can load its
tools before saving. Probe failures read as short localized messages with
the raw error behind Details instead of the probe's English text.

Loaded names are dropped when the connection fields change, since they may
no longer be this server's tools; editing Allow or Deny keeps them.

* docs(mcp): say Load tools probes the dialog's current settings

The MCP and UI references said the button starts the saved server and that
a new server must be saved first, which is no longer true.

* feat(ui): pick MCP tools from a loaded checklist

Typing exact tool names into allow/deny chip inputs made users guess
names the server already knows. The Tools section now loads the
server's tool list and lets users tick which tools the model gets;
unticking writes the exact name to deny, re-ticking removes it (and
adds it to a non-empty allow list), and rows removed by a deny
wildcard are locked with the rule named in a tooltip.

Wildcard and unlisted rules stay editable as chips in the same box,
and an outcome summary tells users which agents honor the list,
which honor it only partly, and which cannot filter tools at all, so
nobody assumes a filter applies where it does not.

* refactor(mcp): drop tools.expose in favor of Pi's own exposure

tools.expose only ever meant something to Pi, yet it sat in the
cross-Agent tool policy, locked Pi's exposure select whenever a policy
was set, and produced an "expose" gap for every other Agent. Pi's
exposure mode now lives only in piOptions.exposure: it can sit next to
a tool policy (only toolExposure still conflicts, since the policy
writes it), allowed tools inherit it, and pi-mcp-adapter's directTools
migrates to it. The flag and field were never released, so they are
removed without a shim.

The dashboard now describes a policy in plain words ("2 tools
excluded") instead of the old "2 denied" shorthand, shows Pi's
exposure on the server list in words, hints that Enter adds a rule,
and no longer leaves "{}" behind when an exposure is set and then
cleared.

* fix(hooks): make import a takeover and plans say what changes

A hands-on trial showed several rough edges in hooks management:

- Importing one per-event candidate such as claude-stop merged every event
  of the file into the entry, so unrelated hooks became managed.
- An imported hook then conflicted on the next sync as an "identical
  unmanaged hook" until --replace, although importing it was the takeover.
- Narrowing an entry was reported as "remove" of the whole file although
  only one event left it, and plans gave no event-level detail.
- A misspelled event such as Stopp was accepted silently and would never run.
- Rewriting a compact settings.json produced half compact, half indented
  JSON and left an empty hooks key Skillshare itself had added.

A name that matches a candidate now picks only that candidate. Saving an
import (Mutation.adopt) records the identical native registrations as the
entry's own even without sync, so the next sync adopts them in place; edits
made outside Skillshare afterwards still conflict. Changes carry added,
updated and removed events, and "remove" is reserved for an entry that leaves
the file. A per-Agent catalog of documented events, from each Agent's
official hooks reference, drives advisory plan warnings and is served at
GET /api/hooks/catalog. JSON edits keep the file's compact or indented style
and drop a hooks key once Skillshare empties the one it created.

* style(ui): keep clean theme switches and picked cards black and white

The clean theme is black-and-white only, so its on switches and picked
cards use ink instead of the green ok and blue accent colors. The playful
theme keeps its own colors.

* feat(hooks): return full file texts from the hooks preview

The dashboard can only show which Agent files a hooks change touches, not
what changes inside them. POST /api/hooks/preview now also returns files[]:
each native file the plan would change, with its current text and the exact
text sync would write, taken from the same plan apply writes from. Other
plan responses stay unchanged, and the route keeps the localhost-only guard.

* feat(hooks): manage Antigravity and Antigravity CLI hooks

Antigravity and its CLI (agy) are skills targets, but their hooks could
not be managed. Both read the same files, ~/.gemini/config/hooks.json and a
project's .agents/hooks.json, so they are one hooks Agent with
antigravity-cli and agy as aliases.

Antigravity's hooks.json maps hook names to blocks of events rather than
one event map. Each Skillshare hook becomes one block named after it, held
as a single owned element, so ownership, adoption, conflicts and restore
work as for the other Agents. Keeping the block's own name lets an import
take the block over in place; a same-named block Skillshare does not own is
a conflict until it is imported or replaced. Disabled blocks are not offered
for import, and edits keep the file's compact or indented style.

The event catalog lists the documented events (seconds timeouts), import
problems are no longer cleared before validation, and the schema and docs
cover the new Agent.

* fix(hooks): replace an edited registration in place

Acceptance found that --replace on a registration Skillshare owned but
someone edited outside appended a second copy: the edited one stayed in the
file, now unmanaged, next to the replacement. When the element at the
record's last written position is owned by no one, replace now overwrites it
there, for both an edit with --replace and 'hooks sync NAME --replace'.

Writing into a one-line array such as "Stop": [{...}] also mixed one-line
and indented layouts; elements written there now stay on that line. Import
candidate lists print an explanation shared by several rows once instead of
on every row.

* feat(ui): rebuild the hooks page around targets, the catalog and real diffs

Editing a hook meant typing event names from memory, repeating each
target by hand and saving JSON the dashboard could not check, and the
preview only listed actions without showing what would change in a
file. The backend now publishes each target's documented events and the
full before/after text of every file a preview touches, so the UI can
guide the whole flow instead of trusting free text.

- Event fields pick from the catalog with descriptions, and show the
  tool filter and timeout unit only where the target has them.
- An empty target tab offers to copy another target's commands, mapping
  events to their closest equivalent and converting timeout units, and
  says when an event has no counterpart.
- Native JSON gets completion, formatting and linting with the line and
  a suggested event, and never drops invalid text when switching back to
  fields; Cmd/Ctrl+S saves without syncing and Esc asks before
  discarding edits.
- The preview shows one card per file with event-level changes and a
  folded line diff that marks the user's own hooks as untouched.
- Import preloads each target's unmanaged hooks, saves only the checked
  ones with adopt so sync does not duplicate them, and keeps pasting as
  a secondary path.
- Antigravity joins the managed targets, the wording says targets
  throughout, and the remove dialog no longer contradicts itself.

* fix(hooks): keep key order and separators when replacing an element

Replacing a registration in place re-encoded it from a Go map, so its keys
came out sorted, and on a one-line array it was minimized without the
spaces the line used: [{"hooks": [{"type": "command", ...}]}] turned into
[{"hooks":[{"command":...,"type":"command"}]}]. The whole line then showed
as changed and read as a rewrite of the user's style.

A replaced element now keeps the replaced one's key order at every depth,
with new keys at the end, and elements written on a one-line array use the
line's own spacing after colons and commas.

* feat(hooks): stop managing a hook while keeping its entries

Removing a hook from the source always queued the removal of its native
entries on the next sync, so there was no way to hand a synced or adopted
hook back to the user. MCP already has this as `remove --keep-files`.

`hooks remove NAME --keep-files` (and `unmanage` in the API mutation)
removes the entry and forgets its ownership records in that scope, so sync
neither removes nor updates what it wrote; the entries show up as unmanaged
and importable again. It is rejected with --sync, like MCP.

The dashboard remove dialog adds "Stop managing" and now says what each
choice does to the target files, including that "Remove from source only"
still deletes the entries on the next sync. Its backup note is neutral and
the dialog is wider to fit the diff.

* fix(mcp): warn that Pi's built-in MCP needs Pi 0.99.0 and no old extension

The first sync after upgrading moves Pi servers off pi-mcp-adapter and
pi-mcp-extension into Pi's mcp.json. A user still on Pi before 0.99.0
silently loses every server, because older Pi does not read that file, and
Pi's docs say an installed extension that registers /mcp replaces the
built-in MCP. Nothing told them either.

The plan now adds one notice, shown by preview, sync and --json, when it
removes an entry Skillshare wrote to mcp-adapter.json, rewrites an owned
entry in pi-mcp-extension's format (the transport field), or the config
still has settings only the extensions read. The ledger check covers a
config that owns adapter entries without saying piExtension.

* docs(mcp): say what Pi needs before the first 0.23.0 sync

The upgrade section described how the config changes but not the two
things a user must do in Pi: run Pi 0.99.0 or later, and remove
pi-mcp-adapter or pi-mcp-extension, which Pi's docs say replace the
built-in MCP. It now shows the sync warning, lists every dropped adapter
option, and says a disabled entry no longer turns a server off for Pi in
that project. The import paragraph claimed sync never changes
mcp-adapter.json; it removes the entries it wrote there.

* fix(ui): make hook diffs, editors and the hooks rail readable

Supervisor and user trial of the rebuilt hooks page found diffs that
read as "we will touch your hook", an editor too small for real hooks,
and text cut short in the rail.

- Diffs: removed lines red and added lines green through new diff theme
  tokens (the one colour exception in the clean theme), removals before
  additions, lines differing only by a trailing comma or whitespace kept
  as context, long lines wrapped, and the "left as is" marker on its own
  line. An adopt-only card says the file is unchanged.
- Editors: native JSON and code editors expand over the dialog and back
  as the same editor, so lint, completion, format, the error count and
  Cmd/Ctrl+S keep working; Esc closes completion first. The invalid-JSON
  explanation sits above the editor.
- Dialogs are 880px like MCP's.
- Main page: full target paths wrap under the name with no inner scroll
  box, the sync card shows the target file, empty descriptions are
  hidden, the unmanaged note avoids an orphaned character, and the row
  menu uses a hooks-specific "each target" label.
- Import names follow the CLI (<target>-<event>) or a script's basename.

* feat(ui): show MCP plan notices before a sync

The API returned the plan's notices, but no dashboard view showed them, so
dashboard users never saw that the 0.23.0 sync rewrites their config or
that Pi's built-in MCP needs Pi 0.99.0 and no old extension. The MCP sync
dialog and the Sync page now list them, translated through mcp.notice.*
keys; a notice the UI does not know is shown as the server sent it.

* fix(install): default CLI installs to the user-local bin directory

Use ~/.local/bin so ordinary script installs and upgrades do not require administrator access. Preserve INSTALL_DIR overrides and existing installations, verify the installed binary directly, and show PATH setup only when needed.

Add offline installer regressions and align installation guidance across all five documentation locales, including automation PATH setup.

Validation: seven offline installer cases, make check in the devcontainer, all five website locale builds, and AI context checks passed.

* fix(ui): let stop managing succeed and open the source config from the header

Stop managing sent a mutation whose plan differs from the removal preview the
dialog had loaded, because the server forgets the ownership records first, so
the revision never matched and every attempt failed as stale. Both the hooks
and MCP remove dialogs now preview that mutation before saving it; it writes no
target file, so there is no diff to review. Its toast also says the entries
stay in the files instead of "Removed".

The source path line under the lists took space most people never read. A
config.yaml button in the page header now shows the full path on hover and
opens the Config page editor; a separate sources.mcp file has no editor there,
so that case copies the path instead.

The Pi chip on a server row no longer mentions other Pi settings.

* test(server): replay the dashboard's hooks and MCP requests against the handlers

UI tests mock the API with one fixed revision, so a dialog that saves with a
revision from the wrong preview passed every vitest while "Stop managing"
failed in real use. These tests send the exact mutation JSON and preview
revision each dialog uses (remove, stop managing, edit, toggle, takeover,
import/adopt, restore, global and project sync) in global, hooks.projects
or mcp.projects, and project-mode scopes, and pin that hooks refuses an
unmanage saved with the removal preview's revision.

* fix(ui): show comma-only line changes in the hooks diff

A line that only gained or lost a trailing comma was shown as unchanged
with its new text, so the preview hid a real byte change to the file.
Lines still align ignoring the comma, so an added sibling does not shift
unrelated lines, but a differing pair now shows as removed and added,
removals first within each change. The user's own event keeps its
"left as is" note on the new line.

* fix(hooks): name the events a Copilot hook file changes

Copilot keeps each hook in its own file, so its plan changes carried no
events and the preview card showed only the action while every other
Agent listed "+ SessionStart" and the like. The planner now compares the
file's hooks map before and after the write and reports added, updated
and removed events the same way shared files do.

* feat(ui): open config.yaml at the section the header button came from

The config.yaml button on the Hooks and MCP pages opened the editor at
the top, leaving the user to scroll for the part that page manages. It
now links to /config?section=hooks or ?section=mcp, and the Config page
puts the cursor on that top-level key and scrolls it into view once the
file is loaded. A config without the key opens at the top as before.

* fix(ui): say what hooks and MCP dialogs will really do

Trying hooks across eight targets showed several places where the
dashboard hid or misstated the outcome:

- Remove and sync writes every pending change of the scope, but the
  hooks and MCP remove dialogs only named the removed entry; they now
  name the other hooks or servers that go out with it.
- With more than three targets, each remove choice spelled out every
  target; it now gives the count.
- Preview cards shrank to their header in a long list and hid the diff.
- A hook's summary listed SessionStart and sessionStart as separate rows
  with no hint of which target runs which; rows now merge case-only
  differences and show their targets' icons.
- Save and sync used the same toast as a plain save.
- The copy panel promised the closest events even when a target had
  none; it now says those events must be picked by hand.
- The Hooks rail's expandable target rows had no accessible name.

* fix(ui): pair hooks diff lines only at the same indentation

Diff lines were aligned ignoring leading whitespace, so appending an
event paired the file's closing braces with braces inside the new block.
Once differing pairs show as removed and added, that turned one comma
change into a run of removed closing braces. Only the trailing comma is
ignored now, so the diff shows the comma pair and the added lines.

* fix(ui): explain each hook removal choice on its own button

The three consequence lines sat in the dialog body, away from the buttons
they describe, and made the dialog long when a hook reached many targets.
Each explanation now shows as a tooltip on its footer button, on hover and
keyboard focus, and is wired through aria-describedby for screen readers.

Tooltip placed button-anchored tips that did not fit below using the
cursor offset, so a two-line tip covered the buttons; it now flips above
the anchor. It also shows nothing without content, which lets the dialog
keep its buttons mounted while the preview loads.

The CJK strings dropped the space between the target text and the
particle, which read as "8 個目標 的".

* fix(hooks): delete the files and folders a removed hook leaves empty

Syncing a hook to an Agent whose hooks file did not exist, then removing
it, left shells behind: `{}` in Claude, Codex, Gemini, Qwen, Droid and
Antigravity files, `{"version":1}` for Cursor, and empty folders such as
~/.copilot/hooks and ~/.pi/agent/extensions. They look like user
configuration and confuse the next import or review.

The ledger now records the shared files Skillshare created and the
folders it made for its outputs. When removal leaves a created file with
nothing but that skeleton, the plan deletes it and says so, and the file
diff shows the deletion. Files and folders that existed before, settings
or comments the user added, and non-empty folders all stay. Apply checks
the skeleton again, so settings added after the preview keep the file.

* fix(hooks): note Copilot's folder trust and use Pi's current package

Running Copilot CLI against a synced project showed that .github/hooks
is skipped until the folder is in trustedFolders, while COPILOT_HOME
hooks run anyway; the Copilot note was the only command Agent note that
did not mention trust. Pi's extension docs now import ExtensionAPI from
@earendil-works/pi-coding-agent, so the hook template follows them. The
old name still loads because the import is type-only, but editors no
longer resolve its types.

* test(hooks): run synced hooks in real Agent CLIs

Unit tests only prove Skillshare writes the native files we believe are
right. This runbook syncs a marker-writing hook for each Agent, starts
the real CLI once per scope with a throwaway HOME and fake credentials,
and checks the markers, so a format or location mistake shows up as a
missing marker. Antigravity and Cursor check credentials before any hook
runs; the runbook lists how to confirm them by hand.

* fix(hooks): write the hooks section in block style

yaml.v3 encodes an empty mapping as flow `{}`, and entries added to it
inherit that style, so the first hook saved after the section was emptied
landed on one unreadable line in config.yaml. The section is now expanded
before it is written, like the MCP section, which also unfolds entries an
earlier save left on one line.

* fix(ui): let Beautify unfold nested one-line YAML

Beautify kept flow collections as written, so a hooks or MCP section
squeezed onto one line stayed that way and the button reported nothing to
change. It now expands flow collections that nest others, and everything
inside them, while short lists such as `targets: [claude, codex]` stay on
one line. Saving still keeps the user's flow style.

* fix(ui): show hook targets once and light them up per event

Each event line repeated its own row of target icons under the header's
icons, and two rows of logos stacked on the right read as clutter. The
header now shows the targets as one overlapping stack, and hovering an
event line fades the targets it does not run on. Screen readers still hear
each line's targets.

* fix(ui): document the hooks section in the config editor

The field panel labelled every key under hooks as an unknown field, which
suggested the section was a mistake. It now explains hooks, its entries,
bindings, events, code, files and projects like the MCP keys.

* docs(hooks): describe the config editor and Copilot folder trust

The hooks page now writes its section in block style, opens the config
editor at hooks:, and the field panel and Beautify understand the
section; none of that was documented. Running Copilot CLI also showed that
project hooks in .github/hooks load only in a trusted folder, which the
destinations section did not say.

* docs(changelog): add 0.23.0 entry

Records native hooks, the MCP tool policy, the dashboard work around both,
and the Pi built-in MCP breaking changes, so users upgrading from 0.22.2
know what moves on their first sync.

* fix(server): validate hooks when the config editor saves

The config editor kept the hooks section as an opaque node and never ran
the hooks checks, so a malformed binding saved successfully and then broke
the Hooks page and `sync --all` until the YAML was repaired by hand. A
project config could also gain `hooks.projects`, which only the global
config may hold. Saving now rejects both with the same message sync gives.

* fix(hooks): keep an Antigravity block's name when importing it

An Antigravity hook is the named block in hooks.json. Importing one under
another name, through `hooks import --from agy NAME` or a renamed row in the
dashboard, planned a new block and left the original unmanaged, so both
ran. Such a takeover is now a conflict that asks for the block's own name,
and the import dialog keeps that name fixed for Antigravity rows.
2026-10-01 02:24:24 +08:00
Willie de0f14f35b docs: link the desktop app from all READMEs
Add the desktop app project to the navigation in English, Japanese, Korean, Simplified Chinese, and Traditional Chinese.
2026-10-01 01:36:18 +08:00
Willie df72e98a96 docs(changelog): add the SSH error fix to 0.22.2
Also drops the hub builder screenshot that the refreshed hub-index page
no longer references; it showed the removed My hubs layout.
v0.22.2
2026-09-30 16:53:32 +08:00
Willie 445ace98ca docs(hub): describe the current Hubs page flow
The hub-index guide and the ui reference still described the old Browse /
My hubs tabs with New Hub, Save draft and Download index, and an in-dialog
Hub manager, none of which exist anymore. Readers following them could not
find the controls.

Rewrite the Web Dashboard section in all five locales around Add or create
a Hub, Add skill, Save, Share -> Download skillshare-hub.json and the hub
add command, using each locale's dashboard labels. Drop the stale
hub-builder-draft.png screenshot, which shows the removed UI.
2026-09-30 16:38:28 +08:00
Willie 6996237796 fix(install): keep the SSH reason when a git remote cannot be read
extractGitFatal kept only git's "fatal:" line, so SSH clone/fetch failures
(install from git@host:..., hub indexes over SSH, updates) reported just
"Could not read from remote repository." and dropped the ssh line that says
why: publickey denied, host key verification, unresolved hostname, or a
refused/timed-out connection.

For that generic message, append the preceding transport line (skipping
"Cloning into" and warning chatter). When the reason is a publickey denial,
WrapGitError adds an "ssh -T user@host" hint. Other errors are unchanged.
2026-09-30 16:35:30 +08:00
Willie 5e2e36c47b chore: release v0.22.2 2026-09-30 16:30:48 +08:00
Willie cba7501916 docs(changelog): add the Hubs and Find skills fixes to 0.22.2 2026-09-30 16:29:11 +08:00
Willie 2c7ab5f70a fix(ui): stop Find skills from installing when nothing is found
When discovery found no skills or agents, the install dialog fell back
to a plain install, so Find skills (or a search row's Install) cloned
the whole repository or copied the folder in as one skill without a
SKILL.md. Discovery already finds a root SKILL.md, so nothing real was
being missed, and the CLI stops with "No skills or agents found" here.
The dialog now says no skills or agents were found in the source and
installs nothing.
2026-09-30 16:28:20 +08:00
Willie daf4e66417 fix(ui): select and star the default hub on the Hubs page
With no own hub and nothing picked, the Hubs page opened on an empty
"pick a hub" state, and when the config saved no default the built-in
Skillshare Hub had no star even though `search --hub` falls back to it.
The page now treats the built-in hub as the default when none is saved
and opens on the default hub (or the first one). An own hub still wins,
as before, and nothing is written to the config.
2026-09-30 16:28:20 +08:00
Willie 9496ba1150 docs(changelog): add 0.22.2 entry
Records mcp check and its --live probe, Pi built-in MCP with the new
default mode, the reorganized MCP dashboard, and the completion,
target link and wording fixes since 0.22.1.
2026-09-30 16:24:04 +08:00
Willie 186f4dfc0f docs(i18n): use the localized MCP labels for backups and the server list
The translated MCP docs name dashboard buttons by their label in that
language, but the new passages kept "Backups and restore" and "Servers"
in English, although every locale translates both.
2026-09-30 16:14:09 +08:00
Willie ab183449ea docs(mcp): describe the reorganized MCP dashboard
The MCP page moved Check and Backups and restore into the Sync box under
Sync MCP, and the "Turn off a global server" button now sits beside the
Servers heading in project mode. Project MCP tabs gained their own Check,
and a Pi server's dialog now starts on the built-in MCP mode. The docs
still named the old places, so readers looked for buttons that had moved.
2026-09-30 16:12:54 +08:00
Willie c6f96f9865 style(ui): lay out project global server rows like the server list
The project MCP tab showed global servers with the old plug tile while
servers only in the project used the two-line row, so one page mixed
two row styles. The global rows now put name, badges and endpoint on
the first line with the switch at the end, and keep the switch notes
on a second line that only appears when there is something to say.
2026-09-30 16:02:12 +08:00
Willie 5da2040f02 feat(ui): move MCP upkeep actions next to the sections they act on
The MCP header carried five buttons in mixed styles, which read as noise
and crowded the two actions people use to add servers. Check and Backups
now sit in the sync card, where the state they relate to already lives,
and the project-only off switch sits on the server list heading. The
project page's Check moves into its sync card the same way.

Server rows drop the repeated plug tile and show the endpoint on the
name line, with the target count pill at the top right. The selected
targets are listed as chips on a second line, and the Pi chip carries its
mode so the separate Pi line is no longer needed.
2026-09-30 15:43:58 +08:00
Willie 9aeba03378 feat(ui): offer full Pi settings when pasting a single server
The paste tab only offered the Pi mode, so setting tool exposure or other
Pi options meant saving the pasted server and then editing it. When the
snippet resolves to exactly one server, the paste tab now shows the same
exposure, options and prune fields as the manual form, prefilled from the
pasted server's own piOptions; only edited fields change it, so untouched
settings round-trip as pasted. Several pasted servers keep the shared mode
only, and import from an Agent is unchanged.

The Pi fields move into a shared PiSettingsFields component, and the
options error message into piOptionsError, so the two tabs cannot drift.
2026-09-30 15:36:45 +08:00
Willie c8e981295a fix(ui): hide the MCP check when there are no servers to check
With no servers the check button still ran and reported "0 servers
have no problems", which reads as a result when there was nothing to
look at. The page and a project's own-server section now offer the
check, and show its note, only when they have servers.
2026-09-30 15:26:21 +08:00
Willie c78e9e62be fix(ui): show the JSONC format tag in the MCP config preview
Kilo Code writes kilo.jsonc, and the format lookup only knew json,
toml and yaml, so its preview had no format tag while every other
Agent file did.
2026-09-30 15:22:51 +08:00
Willie 1b8c4f3e82 style(ui): highlight the MCP config preview and scroll its file list
The preview showed Agent files as plain text, which made nested JSON
hard to scan, and a long target list pushed the dialog taller instead
of scrolling on its own. Render the file with CodeView so keys and
values are coloured and lines numbered, read .jsonc with the JSON
highlighter (Kilo Code's file), and cap the list at the code pane's
height so it scrolls independently.
2026-09-30 15:20:22 +08:00
Willie 1930a37e7c style(ui): align the preview file list with the file header
The first list item started at the top of the pane while the header
icon beside it sat centred in a 32px row, so the two columns looked
offset. Nudge the list down so its first item lines up with the icon.
2026-09-30 15:18:23 +08:00
Willie fb16fcc3d1 style(ui): widen the MCP paste and import dialog to match
The paste tab of the add-server dialog opens MCPImportDialog, which
stayed at 640px after the manual tab moved to 880px, so switching tabs
changed the dialog width and pasted snippets scrolled sideways.
2026-09-30 15:16:35 +08:00
Willie 524c103011 style(ui): widen the MCP server and config preview dialogs
The preview now shows the file list and the file content side by side,
and 720px left the content pane too narrow, so long paths and JSON lines
scrolled sideways. The paste tab had the same problem with pasted
snippets.
2026-09-30 15:14:46 +08:00
Willie b780f268a7 feat(ui): show every Agent file side by side in the MCP config preview
The old preview picked one Agent at a time from a dropdown, so it hid
how many files Sync would write and whether they land in the global or
a project scope. The preview now lists the Skillshare source and every
target Agent with its file path relative to the scope, shows the picked
file in full next to the list, counts the files Sync writes, and names
the scope (global, or the project and its root). Render errors stay
with the Agent they belong to.
2026-09-30 15:11:39 +08:00
Willie 88855431dd docs(mcp): describe the built-in Pi default
The Pi section told scripts to always pass --pi-extension and said new
setups "can choose" builtin, which no longer matches: mcp add, mcp import
and the dashboard dialogs now store builtin for a new server that reaches
Pi without a mode. Say so, note that the default does not follow other
servers' mode, and keep the ja, ko, zh-Hans and zh-Hant pages aligned at
the same positions.
2026-09-30 15:09:31 +08:00
Willie a044b2397b feat(ui): start new Pi servers on the built-in mode
The add dialog preselected the mode of the first existing server, so a
user with one pi-mcp-adapter server got the adapter for every new server,
and the import dialog blocked on "choose a mode" when importing into Pi.
The maintainer decided new servers default to Pi's built-in MCP and that
the default must not be inferred from other servers.

A new server now starts on builtin and the defaultPiExtension prop is
gone. Editing keeps the server's stored mode, and a server that has none
still asks for one. Import into Pi no longer blocks: a picked mode
applies to every server, otherwise each keeps the mode it carries and
the rest are built-in.
2026-09-30 15:09:26 +08:00
Willie 83ac85bae4 feat(mcp): default new Pi servers to the built-in MCP
`mcp add --target pi` without `--pi-extension` failed at render time with
"Pi requires piExtension", so scripts had to know about Pi's modes before
they could add anything. The maintainer decided new servers that reach Pi
should use Pi's built-in MCP (Pi >= 0.99.0) when no mode was chosen.

`mcp add` and `mcp import` now store `piExtension: builtin` at creation
time when the server's own or inherited targets include Pi or a Pi
account. The mode of other servers is not consulted, stored values are
never rewritten, and switch-only entries keep inheriting the global
server's mode. renderPi still refuses an entry without a mode, so a
hand-written config stays explicit.

Integration tests prove the built-in file follows the scope:
~/.pi/agent/mcp.json globally, <root>/.pi/mcp.json in project mode and
for a server under mcp.projects.
2026-09-30 15:09:19 +08:00
Willie be18505dae fix(completion): complete missing subcommands and flags
The five completion scripts are hand-written and had drifted from the
CLI's argument parsing. Some entries sent users down paths that no longer
exist: `backup restore` backed up a target named "restore", `extras mode`
only printed help, `install --source` failed as an unknown option, and
`hub index --audit-skills` was rejected because the flag is `--audit`.
pull, push and commit were offered -p/-g, which they ignore.

Those stale entries are gone, and the scripts now complete:
- backup files list/show/restore, audit rules disable/enable/severity/
  reset/init, ui start/stop, mcp edit (bash, PowerShell, Nushell)
- sync scopes and the `agents` kind keyword where commands accept it
- flags the CLI parses but no shell offered, among them sync --quiet,
  status --json, new/search flags, enable/disable --kind, backup
  --delete/--all, restore/trash --all, ui --base-path/--clear-cache/--app,
  hub add --label, hub default --reset, mcp --disabled/--keep-files,
  analyze --verbose/--filter, init --git-root/--visible/--config and
  the extras subcommand and `extras <name>` flags
- fish: the target filter flags, --agent and --config-dir, and restore

PowerShell also stops swallowing a flag typed as the second word for
commands that have a subcommand list, so adding list, sync and the other
kind-aware commands to that table keeps their flag completion.

The completion reference page in every locale listed the stale
subcommands; it now lists the current ones.
2026-09-30 15:08:35 +08:00
Willie 3106f7d4a3 fix(i18n): say 目标 instead of target in Simplified Chinese
Same cleanup as zh-TW: buttons and messages such as "从 target 导入"
mixed an English noun into zh-CN copy that elsewhere already says 目标.
The config field names targets (skill frontmatter, config.yaml section)
stay as written.
2026-09-30 15:07:46 +08:00
Willie eb4e217467 fix(i18n): say 目標 instead of target in Traditional Chinese
Buttons and messages such as "從 target 匯入" and "{count} 個 target
同步失敗" mixed an English noun into zh-TW copy, while the rest of the
dashboard already calls targets 目標. The config field names targets
(skill frontmatter, config.yaml section) stay as written.
2026-09-30 15:05:45 +08:00
Willie fb6325df88 fix(ui): name the only Agent in the MCP config preview
The preview always showed an Agent picker, so a server with one target
got a dropdown with a single option. With one Agent the preview now
names it; the picker appears only when there is a choice.
2026-09-30 14:57:42 +08:00
Willie 54d0d5eed0 docs(wiki): require all five shell completions for command changes
The completion scripts are written by hand and never read the CLI's
dispatch, so new subcommands (mcp edit in bash and fish, backup list
and show in fish) went missing in some shells without any test failing.
Contributors now have an explicit rule and a completion-criteria check
for it.
2026-09-30 14:53:16 +08:00
Willie 74c17c10c0 test(ui): drop the slow Pi untick case from the MCP server dialog
It ran the same long click sequence twice and exceeded the 5s timeout
whenever the whole suite ran in parallel, failing unrelated runs. It
guarded a narrow case (Pi settings typed, then Pi unticked before the
first save) whose worst outcome is unused Pi fields in the source.
2026-09-30 14:50:14 +08:00
Willie 71583e1cf4 fix(completion): complete the remaining mcp flags in fish
Fish offered only the Pi and check flags for mcp and left out edit,
while bash and zsh completed --url, --target, --sync, --dry-run and the
rest. The fish script now lists the same mcp flags and subcommands.
2026-09-30 14:50:14 +08:00
Willie 69963c69f1 fix(ui): open a dashboard target on its own page
Each dashboard target row, Playful pin note, and "needs attention" entry
names one target but linked to the target list, so reaching that target
took a second click and a search. They now open the target's detail
page; "Manage targets" still opens the list.
2026-09-30 14:43:28 +08:00
Willie cb4b55a91b test(mcp): cover --live in the mcp check runbook
Unit tests use a fake server built from the test binary, so nothing
exercised --live against separate real processes, a real HTTP server
or the process tree a server leaves behind. Steps 8-13 use sh stdio
servers (server/discover, initialize only, one that ignores SIGTERM and
starts a child, one that crashes), a Python server that answers 401,
and an unreachable URL, and check that nothing starts without --live.

Refs #141
2026-09-30 14:42:50 +08:00
Willie 1bb37a89a9 docs(i18n): translate mcp check --live docs
The English mcp reference gained the --live and --timeout flags, the
Probe servers live section and the changed safety note, so the ja, ko,
zh-Hans and zh-Hant pages would otherwise still say that Skillshare
never starts a server. Anchors and code blocks match the English page.

Refs #141
2026-09-30 14:42:49 +08:00
Willie 0e0899a4c7 fix(ui): size the project MCP label column to its labels
The label column was a fixed 110px to fit the Pi adapter label, so
projects without that row showed a wide gap between "Targets" and its
pill. The column now sizes to its labels, and the expanded Agent picker
sits in the value column of the same grid instead of a hardcoded indent
that only matched the old width.
2026-09-30 14:39:12 +08:00
Willie 3c2d0a169e docs(mcp): document mcp check --live
--live is the first command that starts a server or calls one, which
the reference and the built-in skill both described as something
Skillshare never does. Readers need to know what it runs (the server
command, with their environment), how it falls back for servers older
than 2026-07-28, what a 401 reports, the timeout, the live JSON object,
and that the dashboard check stays static.

Refs #141
2026-09-30 14:38:54 +08:00
Willie 8c98ab3b51 test(completion): exercise zsh and fish completions
The completion tests only grepped the generated scripts, so a script
that parses but offers nothing, or a flag listed in the wrong place,
passed. These tests load the scripts in a real fish (complete -C) and a
real zsh (compinit under zpty, capturing what compadd receives) and
assert the mcp subcommands and the mcp check flags, including --live
and --timeout. They skip where the shells are not installed; the
testing wiki says how to run them in a throwaway container.

Refs #141
2026-09-30 14:37:43 +08:00
Willie 733d20aace fix(ui): drop the circle from the MCP check problem icon
The success state already uses a plain check; the problem and error
states still used a circled alert icon, so the note's leading icon
changed shape between states. A triangle alert keeps both plain.

Refs #141
2026-09-30 14:35:46 +08:00
Willie 33c64a78c2 feat(completion): complete mcp check --live and --timeout
mcp check gained --live and --timeout, and a flag that no shell offers
is one users do not find. All five completion scripts list both with
the other mcp flags, and the all-shells test asserts they are present.

Refs #141
2026-09-30 14:35:45 +08:00
Willie b7969308bf feat(mcp): probe servers live with mcp check --live
The static check can say a variable is set and a command is on PATH,
but not whether the server actually starts and speaks MCP, which is the
other half of "synced, but the Agent does not see it".

--live runs after the static checks and only for servers without a
static error. A stdio server is started with the current environment
plus its env and fromEnv values, probed with server/discover and, for
servers before 2026-07-28, the initialize handshake, then stopped:
stdin closed, then SIGTERM and SIGKILL to its process group. A remote
server gets a Streamable HTTP POST with its resolved headers; a 401
reports the WWW-Authenticate resource metadata as a warning and never
signs in. Each probe has one timeout (--timeout, default 10s), a few
run at once, and configured values are redacted from every message.

Without --live nothing is started and no request is sent, and the
dashboard API stays static.

Refs #141
2026-09-30 14:35:41 +08:00
Willie 35a4092bca feat(ui): run MCP check from the project page
The check API already reports servers under mcp.projects, but only the
global MCP page could run it, so problems with a project's own servers
never showed where those servers are managed.

The project view now has the same Check button, summary note, and
per-row findings as the MCP page. Findings are scoped by the server's
project root, because names repeat across scopes: a global server with
the same name must not mark a project row, and the global page keeps
ignoring project findings.

Refs #141
2026-09-30 14:29:21 +08:00
Willie 9a25e34938 fix(ui): keep MCP restore preview height stable
Switching backups replaced the preview with a small spinner, resizing the centered dialog on every selection. Keep a fixed, scrollable preview viewport across loading, results, and errors to prevent the dialog from jumping.

Add regression tests for viewport and dialog identity, focus and list scroll preservation, and restoring only with the selected backup's completed preview revision.
2026-09-30 14:20:36 +08:00
Willie 3779be1cef docs(i18n): translate mcp check docs
The English mcp reference gained the mcp check section, its --no-dns
flag, the project-server coverage, the JSON report fields and the
dashboard Check button, but the ja, ko, zh-Hans and zh-Hant pages did
not, so readers of those locales could not find the command at all.

Add the same content at the same positions with identical anchors,
unchanged code blocks, and the dashboard's own localized button label.
2026-09-30 14:17:07 +08:00
Willie 3d23b4a964 test(mcp): add mcp check E2E runbook
Integration tests cover the check with stubbed lookups and a sandbox, but
not the real resolver, the NO_COLOR human output, or the dashboard endpoint
served by skillshare ui. The runbook drives one global config through every
finding, including an mcp.projects root, and checks exit codes, the --json
shape, --no-dns, name filtering, and GET /api/mcp/check with and without
?dns=0. It passed 7/7 under mdproof in a fresh ssenv.
2026-09-30 13:49:07 +08:00