filepath.Walk/WalkDir silently skip symlinked root directories because
os.Lstat sees the root as a non-directory symlink and never enters it.
This affected update, uninstall, reconcile, and server handlers when
the source directory was a symlink (common with dotfiles managers).
Extract ResolveSymlink() from sync.go into internal/utils/path.go and
apply it at every filepath.Walk/WalkDir callsite on source/target dirs.
Also add containment guards to resolveGroupSkills (uninstall) and
resolveGroupUpdatable (update) to reject group directories that are
symlinks pointing outside the source tree.
- Remove duplicated RateLimitError, newGitHubRequest, newGitHubClient,
checkRateLimit from internal/version — now uses internal/github client,
which also fixes missing `gh auth token` fallback for version checks
- Add GH_TOKEN as fallback in install.resolveToken() for GitHub platform,
matching github.GetToken() resolution order (GITHUB_TOKEN → GH_TOKEN)
- Add GH_TOKEN to sanitizeTokens() redaction list
- Extract shared IsAuthError() in install/auth.go; push.go and
wrapGitError() both delegate to it (adds "Access denied" coverage)
- Consolidate shouldFallback*TrackedClone auth checks via isAuthOrAccessError()
- Thread single *http.Client through search.Search() and all callees,
reducing ~60 redundant TLS handshakes to connection-pooled reuse
- Pass *http.Client to downloadFile() instead of creating per-file clients
- Replace sourceHost() with extractHost() (same package, identical purpose)
- Remove unused isGitRepo() alias; callers use IsGitRepo() directly
- Extract shared applyDetailScroll into tui_helpers.go (was duplicated
across diff_tui.go, log_tui.go, audit_tui.go)
- Create utils.FileHash and utils.FileHashFormatted, replacing private
copies in install/meta.go and audit/audit.go
- Export install.MetaFileName constant, use from diff_file.go
- Replace double SHA-256 in fileContentsEqual with streaming byte compare
for early-exit efficiency
- Add 1MB size cap to generateUnifiedDiff to prevent performance issues
- Move noTUI into diffRenderOpts struct, simplifying function signatures
- Fix non-TTY progress bar not incrementing for grouped skills in Phase 2
- Fix Unicode truncation in UpdateTitle using runewidth instead of len()
- Fix IP address regex missing end-of-line bare IPs (add $ anchor)
- Fix gofmt alignment in updateTarget struct comments
- Extract sliceHasName[T] generic helper to deduplicate universal detection
- Add nil meta defensive warning with skipped count in grouped updates
- Replace hand-rolled contains/containsStr with strings.Contains in tests
- Add red team TC-20b for inline code fetch-with-pipe detection
Optimize grouped repo updates by skipping reinstall when installed metadata already matches remote state (commit match, or subdir tree-hash match when HEAD moved).
Emit per-skill grouped progress events so the batch progress bar advances continuously instead of appearing stuck at 0%.
When skipping by tree-hash match, best-effort refresh meta.Version to latest commit to keep status/version output current.
Add unit tests covering commit/tree-hash skip behavior and metadata version refresh.
When update --all processes many skills from the same repo, avoid reinstall/copy when installed metadata already matches the fetched repo state.
For root skills, skip when meta.Version matches repo commit. For subdir skills, require both meta.Version and meta.TreeHash to match. Added unit tests for match/mismatch cases.
UpdateGitIgnore/RemoveFromGitIgnore were called per-skill inside loops,
re-reading the entire .gitignore each time. With large files (100K+ lines
in project mode), this caused O(N×M) complexity and process hangs.
- Add UpdateGitIgnoreBatch and RemoveFromGitIgnoreBatch (single read/write)
- ReconcileProjectSkills: collect entries during walk, batch-update once
- uninstall (global + project): batch-remove after loop, not per-iteration
- Fix spinner WithRemoveWhenDone in StartSpinnerWithSteps
- Add E2E runbook for gitignore batch performance validation
Prevent accidental duplicate installs when the same repo is already
installed at a different path (e.g., --into vs root). Same-repo
reinstalls now show a friendly skip indicator instead of an error.
- Add CheckCrossPathDuplicate() with URL normalization (HTTPS/SSH)
- Add ErrSkipSameRepo sentinel for graceful skip flow control
- Add checkExistingConflict() with repo URL comparison
- Fix --force hint to use repo URL (not per-skill subpath) and
include --into when applicable
- Add dedup check to Web UI install endpoints (HTTP 409)
- Group skipped skills by directory with repo label in summary
Root-level skills (SKILL.md at repo root) have meta.Subdir="" but
discoverSkills() returns Path=".". The mismatch caused lookup failure
in batch update, falsely reporting these skills as stale/deleted.
Switch config install and search install UI from plain spinner to
TreeSpinner with StepResult summary showing installed/skipped/failed
counts and elapsed time. Add git clone progress callback to spinners
so users see real-time cloning status.
- Add Quiet field to InstallOptions for suppressing per-skill output
- Add Skipped field to ConfigInstallResult for accurate summary
- Update integration test assertion to match new summary format
When a registry has multiple skills from the same git repo,
InstallFromConfig now clones the repo once and installs each skill
from the local clone via InstallFromDiscovery. This mirrors the
optimization already present in search_batch.go for hub installs.
The install flow is restructured into 4 phases:
1. Tracked repos (unchanged, each does its own clone+discover)
2. Grouped plain skills (clone once per repo, install from discovery)
3. Singles (unchanged per-skill Install flow)
4. Reconcile config
Skills that fail to match in grouped discovery fall back to Phase 3.
Use a repo-root source in grouped search installs by normalizing from CloneURL instead of carrying subdir Raw values. This prevents malformed metadata sources (for example duplicated subdir paths) and keeps provider-agnostic behavior for GitHub/GitLab/Bitbucket/Azure and SSH URLs.
Also centralize discovery source formatting for metadata so whole-repo SSH installs use //subdir syntax consistently.
Add regression coverage:
- cmd unit tests for grouped clone source normalization across providers
- install unit tests for discovery source formatting (including SSH)
- integration test in tests/integration that verifies grouped install metadata source round-trips through ParseSource.
- Report "partial" status for sync/install/update/uninstall when some
items succeed and others fail
- Instrument 6 new commands: check, diff, trash, init, upgrade, and
all mutating commands now log to operations.log
- Auto-truncation via WriteWithLimit with configurable log.max_entries
(default 1000) and 20% hysteresis to avoid truncating every write
- Stats engine: computeLogStats with per-command breakdown
- CLI --stats flag with colored output and ✓ok/total ratios
- TUI stats panel (toggle with 's'): bar charts, status distribution,
last operation timestamp
- TUI stats footer: compact always-visible summary line
- TUI detail panel: j/k scrolling for long entries, proportional
list/detail layout (40%/60%)
- Web API: GET /api/log/stats endpoint
- Updated website docs for log command
Add PlatformAzureDevOps detection (dev.azure.com, ssh.dev.azure.com,
visualstudio.com) and AZURE_DEVOPS_TOKEN env var support. Token is
auto-injected via git config insteadOf rewrite, same pattern as
GITHUB_TOKEN/GITLAB_TOKEN/BITBUCKET_TOKEN.
Update error messages, sanitizeTokens redaction, environment-variables
docs with PAT creation guide and official Microsoft docs link, and
url-formats docs with Azure DevOps auth section.
Azure DevOps uses 4-segment paths (org/project/_git/repo) which the
existing 3-segment gitHTTPSPattern misparses. Add dedicated patterns
for modern HTTPS (dev.azure.com), legacy HTTPS (visualstudio.com),
and SSH v3 (ssh.dev.azure.com) formats. Also add ado: shorthand
(e.g. ado:org/project/repo) for quick installs.
Includes TrackName support (org-proj-repo format), 16 new test cases,
and url-formats.md documentation with platform support table update.
Enrich the single-skill install SkillBox with the SKILL.md frontmatter
description field, giving users useful context instead of repeating the
skill name. License line appended when present.
- Add Description field to SkillInfo struct
- Use ParseFrontmatterFields to read description + license in one pass
- Extract buildSkillBoxDesc helper for the two single-skill call sites
The // subdir syntax (e.g., repo//skills/foo) stores meta.Subdir with
a leading "/". git rev-parse and ls-tree paths never have leading
slashes, causing tree hash lookups to fail silently.
Strip leading "/" in getSubdirTreeHash(), resolveSkillStatuses(), and
handler_check.go. Add LeadingSlash unit test and E2E runbook.
Previously `skillshare check` compared repo-level commit hashes, causing
all skills from a registry repo to show "update_available" whenever any
commit was pushed — even if the individual skill's files were unchanged.
Now each skill records its git tree hash (subdir-level SHA) at install
time. During check, a three-tier comparison is used:
1. Fast path: commit hash matches → up_to_date (zero extra cost)
2. Tree hash path: blobless fetch (~150KB) + batch ls-tree → per-skill
comparison; unchanged subdirs stay up_to_date
3. Fallback: no tree hash (old installs) → commit comparison (unchanged)
Also fixes pterm progress bar printing twice when it auto-stops at 100%.
Introduce InstallContext interface to abstract global/project behavioral
differences, push config-based install logic down to internal/install,
and merge the nearly-identical Git discovery/subdir handlers.
- Add InstallContext interface (SourcePath, ConfigSkills, Reconcile,
PostInstallSkill, Mode) with SkillEntryDTO to avoid circular imports
- Add globalInstallContext and projectInstallContext implementations
- Extract InstallFromConfig() to internal/install/install_config.go,
replacing the 90%-identical installFromGlobalConfig/installFromProjectConfig
- Merge handleGitDiscovery + handleGitSubdirInstall into handleGitInstall,
branching on source.HasSubdir() for the few differences
Swap fast path order: sparse checkout is now fast path 1 (works for all
hosts including file://), GitHub Contents API is fast path 2 (fallback
when sparse is unavailable or fails). Also reset subdirPath on sparse
failure to ensure proper fallback chain.
Fix red team helpers to inject -g flag after subcommand, preventing
.skillshare/ auto-detection from hijacking global-mode tests.
Add blocked section assertions to TestUpdate_BatchAll_FailsOnMalicious.
UpdateSkillsFromRepo was using filepath.Join(sourceDir, meta.Subdir) to
derive the local destination, but meta.Subdir is the repo-internal path
(e.g. "skills/foo") which may differ from the local install path ("foo/").
This created leaked copies at sourceDir/skills/foo/ alongside the correct
sourceDir/foo/, doubling the skill count on subsequent scans.
Change skillTargets from []string to map[string]string where key is the
repo subdir (for discovery lookup) and value is the local absolute path
(provided by the caller who already knows where the skill is installed).
file:// URLs with subdirectory paths (e.g., file:///repo/skills/alpha)
were passed whole to git clone, which fails because the full path isn't
a git repo. Add // separator support matching the existing SSH convention:
file:///path/to/repo//skills/alpha → CloneURL=file:///path/to/repo, Subdir=skills/alpha
Also updates E2E runbook Steps 10-11 to use the // syntax and improves
cli-e2e-test skill with cleanup prompt, cd /workspace note, and Go test template.
standardized the command-line interface to ensure professional visual
consistency, accurate path reporting, and synchronized audit logic across
all modes.
Visual and UX Enhancements:
- Adaptive Skill Cards: Redesigned the bulky summary box into a compact card
that correctly reports relative installation paths and handles missing
descriptions with fallback messaging.
- Connected Hierarchical Trees: Implemented a standardized tree layout
(StepStart, StepContinue, StepResult) for all single-item tasks, integrating
success status and execution duration as final nodes.
- Intelligent Audit UI: Optimized 'Audit Findings' headers to perfectly align
with risk results, ensuring no empty sections appear on CLEAN results.
- Ephemeral Progress Tracking: Configured spinners to auto-indent within the
hierarchical structure and disappear completely upon completion to maintain
clean terminal logs.
Logic and Reliability Fixes:
- Path Parity: Fixed a bug where the '--into' flag was not accurately
reflected in the UI cards during installation.
- Audit Completeness: Restored missing security scans for certain Git-based
installation paths.
- Code Parity: Unified recursive discovery and display logic between Global
and Project update modes.
Validation:
- Successfully verified with 'make check' (all 150+ unit and integration
tests passing).
Follow-up cleanup after install.go split.
Changes:
- clarify that install.go is a thin facade with delegated implementations
- add explicit docs for non-progress discovery internal adapters
- normalize internal query helper comment wording to match impl naming
No behavior change intended.
Verification:
- go test ./internal/install -count=1
- go test ./cmd/skillshare -run 'TestRenderInstallWarnings_CompactSuppressesExtraDetails|TestRenderBlockedAuditError_TrackedRepositoryContext' -count=1
- go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/Users/williehung/Developer/Apps/github/skillshare/bin/skillshare go test ./tests/integration -run 'TestInstall_Subdir|TestInstall_Track_BlocksCritical' -count=1
Restructure the install package to reduce install.go size and isolate responsibilities without changing exported API signatures.
Changes:
- convert internal/install/install.go into a thin facade (types, test hook, exported wrappers)
- extract install flows into install_apply.go
- extract discovery flows into install_discovery.go
- extract update flow into install_update.go
- extract audit logic into install_audit.go
- extract git helpers into install_git.go
- extract tracked repo flow into install_tracked.go
- extract updatable/tracked query helpers into install_queries.go
- extract copy helpers into copy.go
Compatibility:
- exported API signatures are unchanged
- package remains flat as package install
- behavior is intended to remain equivalent; only code organization changed
Verification run before and after split:
- go test ./internal/install -count=1
- go test ./cmd/skillshare -run 'TestRenderInstallWarnings_CompactSuppressesExtraDetails|TestRenderBlockedAuditError_TrackedRepositoryContext' -count=1
- go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/Users/williehung/Developer/Apps/github/skillshare/bin/skillshare go test ./tests/integration -run 'TestInstall_Subdir|TestInstall_Track_BlocksCritical' -count=1
- go test ./...
Clarify audit blocking output for tracked repository installs and updates.
Changes:
- update tracked install audit block errors to state findings were detected in tracked repository
- update tracked update audit block and rollback messages with tracked repository context
- when tracked install is blocked by audit, show spinner state as Blocked by security audit instead of Failed to clone
- enhance blocked audit summary rendering to append in tracked repository when the error context indicates a tracked repo
- add unit test coverage for tracked repository context in blocked audit rendering
Verification:
- go test ./cmd/skillshare ./internal/install -count=1
- go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/Users/williehung/Developer/Apps/github/skillshare/bin/skillshare go test ./tests/integration -run TestInstall_Track_BlocksCritical -count=1
Implement remaining Issue 46 optimizations and developer experience fixes.
Install and update optimization:
- optimize install --track for subdirectory sources by attempting sparse checkout first while preserving git metadata
- fallback to existing tracked clone strategy on sparse capability or sparse path errors
- clean sparse created destination before fallback clone to avoid destination already exists failures
- improve tracked install spinner wording for subdir sources
- add tracked subdir unit tests for sparse success and sparse to full clone fallback
Progress user experience:
- normalize git progress lines by stripping volatile transfer rate suffix
- dedupe and throttle spinner and tree spinner update frequency to reduce tty flicker
- add unit tests for spinner progress normalization and throttling behavior
GitHub API messaging:
- improve rate limit guidance to suggest setting token env vars or using gh auth login
Devcontainer isolation:
- make ssenv enter command mode run from isolated environment cwd
- fix setup global init detection to use skillshare status global mode
- add auto mode hint in devcontainer wrapper when workspace project config takes precedence
E2E and tests:
- expand Issue 46 runbook with install, install track, update, no token fallback, sparse paths, and isolation checks
- update compact warning output test expectations to match current grouped warning rendering
Verification:
- go test internal install package
- go test internal install sparse and tracked subdir tests
- go test internal ui package
- go test cmd skillshare package
- go build skillshare binary and run integration TestInstall_Subdir
- run tracked subdir tests inside devcontainer
Implement Issue #46 across install/update paths to reduce perceived hangs and improve subdir installation performance on large repositories.
Main changes:
- Add git progress streaming primitives in internal/install/git_progress.go.
- runGitCommandWithProgress supports stderr streaming callbacks in TTY mode.
- scanGitProgress handles both CR and LF progress delimiters.
- Thread InstallOptions.OnProgress through clone/pull/discovery/install/update paths.
- Keep non-TTY behavior quiet to avoid noisy logs.
- Add TreeSpinner.Update for live message updates.
- Add progress-aware git update APIs in internal/git/info.go:
- PullWithProgress and ForcePullWithProgress (keep PullWithEnv/ForcePullWithEnv for compatibility).
- Introduce shared GitHub client utilities in internal/github/client.go.
- Centralize token lookup, request construction, and rate-limit handling.
- Refactor internal/search/search.go to use shared client while preserving compatibility aliases.
- Add GitHub/GHE API subdir fast path in internal/install/github_download.go.
- github.com => api.github.com
- github-like enterprise hosts => https://<host>/api/v3
- On API failure, emit warning and fallback to git-based flows.
- Add sparse checkout fallback for non-GitHub subdir sources in internal/install/sparse_checkout.go.
- Use filter+no-checkout+depth=1 then sparse-checkout set + checkout.
- Extend discovery/install metadata plumbing.
- DiscoveryResult now includes CommitHash and Warnings.
- install/discover subdir paths preserve warnings and commit hashes from API/sparse/full-clone flows.
- Preserve compatibility and UX expectations.
- Keep existing action strings (for tests/UI stability).
- Keep legacy discover/pull APIs as wrappers around new progress-aware variants.
- Improve --track download efficiency.
- Track clone now attempts --filter=blob:none --depth 1 --single-branch first.
- Falls back to full clone only on remote capability mismatch, not on auth/not-found errors.
CLI wiring:
- cmd/skillshare/install.go
- TTY handlers now pass progress callbacks and use with-progress discover APIs.
- Subdir handler shows API-vs-clone stage messages and renders discovery fallback warnings.
- cmd/skillshare/update.go and cmd/skillshare/update_project.go
- Use PullWithProgress/ForcePullWithProgress for tracked repos.
- Ensure reinstall/update install flows forward progress callbacks.
Tests added/updated:
- internal/install/git_progress_test.go
- internal/install/github_download_test.go
- internal/install/sparse_checkout_test.go
- internal/install/tracked_clone_test.go
- internal/install/source_test.go (GitHubOwner/GitHubRepo coverage)
- internal/git/info_test.go (PullWithProgress/ForcePullWithProgress)
- tests/integration/install_subdir_optimization_test.go
- tests/integration/install_online_test.go (GitHub API subdir case)
Validation performed:
- go test ./internal/install -count=1
- go test ./internal/git -run 'Test.*Pull.*' -count=1
- go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY="/Users/williehung/Developer/Apps/github/skillshare/bin/skillshare" go test ./tests/integration -run 'TestInstall_Subdir|TestUpdate_' -count=1
- go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY="/Users/williehung/Developer/Apps/github/skillshare/bin/skillshare" go test ./tests/integration -run 'TestInstall_Track_|TestUpdate_TrackedRepo' -count=1
- go test -tags online ./tests/integration -run TestInstall_GitHubSubdirViaAPI -count=1
- make lint
- make test
- SectionLabel(): dim section headers for visual grouping in batch output
- StepFail(): preserve pre-styled ANSI labels instead of double-wrapping
- Spinner Success/Warn: skip elapsed suffix when <50ms (avoids noise in tests)
- InstallOptions.AuditVerbose field for --audit-verbose flag plumbing
- Update install integration test assertions for batch compact format
InstallTrackedRepo and updateTrackedRepo had no security audit,
allowing --track to bypass all supply-chain checks. This adds
auditTrackedRepo (removes repo on block for fresh installs) and
auditTrackedRepoUpdate (git reset rollback for updates), plus
input validation, testable removeAll, and hardened error handling
across audit/install/uninstall paths.
Regular skills (non-git, metadata-based) now support --diff flag using
hash-based file comparison, display audit results after update, and
properly enforce the audit gate by not passing Force to inner Install.
Pin sha256 file hashes in .skillshare-meta.json during install/update.
Audit now detects content-tampered (MEDIUM), content-missing (LOW),
and content-unexpected (LOW) findings. Backward-compatible: skills
without file_hashes in meta are silently skipped.
Supply-chain hardening Phase 2:
- Add post-pull audit gate: HIGH/CRITICAL findings auto-rollback in
non-interactive mode (fail-closed), prompt in TTY mode
- Use full 40-char commit hashes for reliable rollback (avoids short-hash ambiguity)
- Add --skip-audit flag to bypass the gate when risk is accepted
- Add --diff flag to show file-level change summary after tracked repo update
- Add GetChangedFiles() and ResetHard() git helpers
- Add audit gate in install --update git-pull path to prevent bypass
Add token auto-injection for private repo support across all platforms:
- Hub search (--hub): normalize web URLs to raw-content URLs and apply
platform-specific auth headers (GitLab, GitHub, Bitbucket)
- Web UI push/pull/update: use *WithAuth variants for git operations
- Export ResolveTokenForURL and DetectPlatformForURL from install/auth
Automatically detect GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, or
SKILLSHARE_GIT_TOKEN and inject credentials via transient GIT_CONFIG_*
env vars during clone and pull. Tokens are never persisted to disk.
Key changes:
- Platform detection (GitHub/GitLab/Bitbucket) with per-platform
username conventions (x-access-token, oauth2, x-token-auth)
- GIT_CONFIG_COUNT safe append — reads existing count to avoid
overriding CI pipeline git config entries
- Token-aware error messages: "no token" shows 3 options (SSH, env
var, credential helper); "token rejected" suggests checking
permissions and expiry
- sanitizeTokens redacts all credential values (including
BITBUCKET_USERNAME) from stderr before surfacing errors
- gitPull also injects auth via getRemoteURL(), fixing the previous
limitation where update failed after HTTPS+token install
Change matchSkillIgnore to compare against skill path instead of name,
enabling patterns like "feature-radar" to exclude all skills under
that group directory. Precise paths like "feature-radar/helper" still
target individual skills. Backward compatible — flat skills have
path == name so existing patterns work unchanged.
Implement three install features with full documentation:
- .skillignore: repo-level file to hide skills from discovery (exact
match + trailing wildcard). Applied during git repo discovery before
any selection prompt.
- --exclude: CLI flag to skip specific skills during multi-skill install.
Filters before the interactive prompt so excluded skills never appear.
Warns when used with direct local-path installs (not applicable).
- License display: shows SKILL.md license frontmatter in selection
prompts and single-skill confirmation screen.
Add 7 integration tests, 2 new doc pages (declarative-manifest,
url-formats), and cross-reference updates across 6 existing doc pages.
When installing from a monorepo where skills live in a nested directory
(e.g. skills/vue-best-practices/), specifying just the skill name as
subdir (owner/repo/vue-best-practices) would fail because the exact
path doesn't exist at the repo root. Now resolveSubdir scans all
SKILL.md files and matches by basename, falling back gracefully with
an ambiguity error when multiple candidates share the same name.
- Distinguish two dev workflows: make ui-dev (local Go) vs
dev-docker-up + pnpm run dev (no Go required)
- Add auto-init to dev profile so container doesn't crash on first run
- Add --cap-add ALL to playground volume init (cap_drop blocks chmod)
- Document port 19420 conflict between playground and dev profile
- Add docker-build vs docker-build-multiarch explanation and GHCR pull examples
- Increase git command timeout to 180s for constrained Docker networks
- Increase online test timeout to 300s
- Align Makefile help text formatting
Allow installing skills into subdirectories for organized folder
structures. Works with all install modes (direct, discovery, tracked)
in both global and project mode.
- Add Into field to InstallOptions and IntoPath() validation
- Update 4 dest-path construction points in CLI with destWithInto()
- Update InstallTrackedRepo for --into prefix in dest and gitignore
- Rewrite ReconcileProjectSkills to use filepath.WalkDir (recursive)
- Add --into to Web UI install handler, API client, and form
- Add 5 integration tests covering local, multi-level, validation,
project mode, and no-source rejection
GetTrackedRepos() and GetUpdatableSkills() now walk subdirectories
recursively so skills organized in folders (e.g. frontend/vue/) are
detected by check and update commands. Previously only direct children
of the source directory were scanned.
Also adds:
- Short name resolution for `update` (e.g. `update vue-best-practices`
resolves to `frontend/vue/vue-best-practices`)
- Fix ReadMeta nil check in updateSkillOrRepo to ensure fallback fires
- Remove logo from `check`, replace with mode-aware header
- New docs guide: Organizing Skills with Folders
- Rename screenshot to organizing-skills-comparison.png
On Windows, filepath.Join produces backslash separators that were
written directly into .gitignore and JSON metadata files. Git does
not match backslash patterns, and metadata subdirs with backslashes
corrupt source URLs during updates.
Use strings.ReplaceAll(s, "\\", "/") at write boundaries — matching
the existing pattern in sync.go — to ensure config/metadata files
always contain forward slashes regardless of OS.