- CHANGELOG.md + website changelog: Unreleased entry for v0.19.16
covering the global `sources:` map feature plus the two behavior
changes (extras init no longer silently backfills extras_source;
extras source command writes to whichever field the user already
configured).
- website/docs/understand/source-and-targets.md: add "Custom Source
Directories" section for global mode mirroring the project-mode
writeup, with examples, backward-compat notes, and a cross-link to
the project-skills page.
Six-step mdproof runbook exercising the v0.19.16 global sources map:
1. Fresh init -g writes sources: map (no legacy source/agents_source/extras_source)
2. Legacy-only config (source: + agents_source:) — ss list still works
3. New sources map (sources.skills + sources.agents) — ss list works
4. Mixed config — sources.skills wins over legacy source
5. ss sync writes to a custom target with sources.skills set
6. ss sync rejects configs that set neither source nor sources.skills
Runs in 0.9s and prevents regressions on either format.
Also: record an mdproof lessons-learned entry for `ss sync --json`
output — it has no top-level `.errors` field; assert `.linked` /
`.details` or rely on exit_code instead.
Fresh `skillshare init` (global) now writes the v0.19.16 `sources:` map
instead of the legacy top-level fields:
sources:
skills: ~/.config/skillshare/skills
agents: ~/.config/skillshare/agents
What changed:
- cmd/skillshare/init.go: construct Config with Sources{Skills, Agents}
rather than Source/ExtrasSource. The --subdir update path writes to
cfg.Sources.Skills accordingly. The --remote re-init path uses
cfg.EffectiveSkillsSource() for git operations so it works whichever
shape the existing config uses.
- internal/config/config.go: add `,omitempty` to Source field so configs
that only set sources.skills don't get a noisy `source: ""` line.
- tests/integration/extras_test.go: rename TestInit_SetsExtrasSource to
TestInit_WritesSourcesMap and assert the new shape (sources map
present, legacy source/extras_source/agents_source absent).
Existing configs are untouched — legacy fields keep working through
Config.Effective*Source helpers. No auto-migration on Save.
Make the v0.19.16 sources map actually do something: route all path
reads through Config.EffectiveSkillsSource() / EffectiveAgentsSource() /
EffectiveExtrasSource() so users who set sources.skills / sources.agents /
sources.extras get the configured paths everywhere.
Mechanical changes (~50 files):
- cmd/skillshare/**: replace cfg.Source / cfg.ExtrasSource reads with
cfg.EffectiveSkillsSource() / cfg.EffectiveExtrasSource()
- internal/server/**: replace s.cfg.Source / s.cfg.ExtrasSource reads
with the same helpers; server.skillsSource() / gitignoreDir() use the
global-mode helper
- internal/config/config_validate.go: validate using EffectiveSkillsSource
while still rejecting configs that set neither field explicitly
- internal/config/reconcile.go, registry.go: read via helpers
Behavioral fixes (paired with the migration):
- extras init / extras source / POST /api/extras no longer silently
backfill the legacy extras_source field — the runtime fallback inside
EffectiveExtrasSource() handles it. This stops surprise diffs in users'
config.yaml after running extras commands.
- extras source command writes back to whichever field the user already
configured (sources.extras if set, otherwise legacy extras_source) so
the update is not shadowed.
- source_type in /api/extras and extras list correctly reports "default"
vs "extras_source" by inspecting the raw (unresolved) configured value;
sources.extras counts as configured for this purpose.
UI:
- ui/src/lib/fieldDocs.ts: neutralize sources / sources.* descriptions
so they describe both project and global modes (Phase 5).
Preserved (intentional):
- Direct writes to cfg.Source / cfg.AgentsSource / cfg.ExtrasSource in
init, migrate.go, cloneForSave, and server.reloadConfig — these are
raw-field writes, not path reads.
- Updated test expectations for the removed backfills.
Mirror project-mode `sources:` map (v0.19.15) on the global Config:
- GlobalSources struct with Skills/Agents/Extras fields (all omitempty)
- Sources field on Config (yaml: sources, omitempty)
- EffectiveSkillsSource(), EffectiveExtrasSource() helpers
- EffectiveAgentsSource() now prefers Sources.Agents over the legacy
AgentsSource field before falling back to <BaseDir>/agents
- Load(): expand ~ in cfg.Sources.* (and AgentsSource, previously missed)
- cloneForSave(): fold $HOME → ~ in cfg.Sources.* for tilde-preserving saves
- RegistryDir cache uses EffectiveSkillsSource() so configs with only
sources.skills (no top-level source:) still resolve a registry root
Schema:
- Add top-level sources property with skills/agents/extras sub-keys
- Mark source/agents_source as legacy in their descriptions
- Drop required:[source] (new configs can use sources.skills only)
Legacy source/agents_source/extras_source fields are retained
unchanged for backward compatibility. Caller migration to the new
helpers is deferred to a later commit.
Adds Status block documenting what actually shipped (sources map only,
no source shorthand) and resolves the two Open Questions (external
gitignore: leave to repo; init -p --source flag: deferred).
- Add 'Custom Source Directories' section to project-skills.md covering
the sources map, common layouts, and constraints (no target alias,
external paths skip gitignore, .skillshare/ for ops dirs, init seeds
default paths).
- Add troubleshooting entries for the two new error classes: malformed
project config (fail-closed) and source/target path overlap.
- 3 malformed-config tests verify uninstall/new/check abort instead of
silently using the default .skillshare path
- 1 overlap test verifies sync rejects sources.skills aliasing a
target path
- Fix pre-existing TestUninstall_AllProject fixture which used
malformed targets: {} (map, not list) — now caught by fail-closed
load
Project-mode 'check agents' previously fell back to .skillshare/agents
when LoadProject failed. With custom sources.agents this could scan
the wrong directory and report green while the configured source is
unchecked. Now returns the load error instead.
ValidateProjectConfig now resolves each target's skills/agents path
and rejects configs where a source aliases or nests with any target
path. Without this guard, sources.skills: .claude/skills with a
claude target makes sync --force delete the source.
check -p now returns an error on LoadProject failure instead of
falling back to .skillshare/skills.
Project-mode disable/enable and new previously fell back to default
.skillshare/{skills,agents} when LoadProject failed. With custom
sources this could write .skillignore/.agentignore or create new
skills in the wrong directory. Now both paths return an error
instead of silently using the default path.
Project uninstall previously fell back to default .skillshare/skills
when config was malformed. With custom sources this could trash skills
from the wrong directory. Now both skill and agent uninstall paths
return an error instead of silently using the default path.
When sourcePath equals projectRoot, filepath.Rel returns ".",
causing callers to write "./<name>/" patterns that git ignores.
Return empty entryPrefix so callers produce "/<name>" instead,
which is a valid root-anchored gitignore pattern.
Reorder handleUninstallRepo to move repo to trash before removing the
.gitignore entry, preventing accidental exposure of tracked content
when trashing fails.
ProjectGitignoreTarget now returns empty strings for source paths
outside projectRoot, since parent-relative patterns (../) are invalid
in .gitignore. All six callers guard on empty gitignoreDir and skip
gitignore management for external sources.
reloadConfig now updates s.cfg.Source and s.cfg.AgentsSource from the
refreshed ProjectConfig so project UI handlers see the latest source
directories after a config edit.
Add ProjectGitignoreTarget helper that computes the correct .gitignore
directory and entry prefix based on whether the source path is inside
.skillshare/ or a custom location. All gitignore write and remove
operations (reconcile, install, uninstall, server handlers) now use
this helper instead of hardcoded 'skills/' prefix.
Fix nil projectCfg panics in three server tests that simulate project
mode by setting projectRoot without projectCfg.
Add ProjectSources struct to ProjectConfig with optional skills, agents,
and extras fields. When set, project-mode commands resolve source paths
from these values instead of hardcoded .skillshare/{skills,agents,extras}/.
Config example:
sources:
skills: ./docs/skills
agents: ./docs/agents
Three EffectiveXxxSource(projectRoot) methods provide the central
resolution logic with fallback to defaults. The projectRuntime gateway
and server layer route through these methods, so most commands get
custom source support automatically.
Closes#153
isExternalOrAnchor passed the raw scheme to isURLScheme which only
accepted lowercase letters, causing uppercase schemes like VSCode://
to be misidentified as dangling links.
- Update antigravity global path to shared ~/.gemini/skills
- Update antigravity project path from .agent to .agents
- Add aliases: gemini, gemini-cli, antigravity-cli
- Remove standalone gemini target (now an alias)
- Update testutil.CreateTarget to match new path
Tighten publisher claim extraction, skip custom URI schemes in dangling-link checks, avoid treating bracket placeholders as markdown links, and allow common documentation domains for external-link noise reduction.
Co-authored-by: Codex <noreply@openai.com>
The tracked repo name resolution was changed to prefer source.Name
over TrackName() in a656e30b, but this integration test still used
TrackName() to compute the expected directory path.
Add PreserveTildeOnSave config flag (default false). When enabled, the
Save path folds $HOME prefixes back to ~ when serializing the in-memory
Config to YAML so the on-disk config stays portable across machines
(e.g. when shared via dotfiles).
The in-memory Config is left untouched; cloneForSave() produces a
shallow copy with path fields rewritten. Mirrors the existing
expandPath() calls performed in Load():
- cfg.Source, cfg.ExtrasSource
- cfg.Targets[*].Path / Skills.Path / Agents.Path
- cfg.Extras[*].Source and Extras[*].Targets[*].Path
Adds:
- utils.FoldHomePath() helper with unit tests (exact-home, child,
sibling-non-home, unrelated-abs, relative, Windows case-insensitive)
- 3 Save-path tests covering default-off, fold-on, and Load→Save
idempotency.
Default off keeps the change backward compatible: existing users see no
behavior difference. Users who share their config via dotfiles can opt
in with:
preserve_tilde_on_save: true
Project mode agent backup (sync --agents, backup -p) creates
.skillshare/backups/ but it was not gitignored — backup artifacts
could be accidentally committed.
Agent backup was added in 95c46ca8 (2026-04-06), after the gitignore
fix in 90c096b8 (2026-03-16) which only covered logs/ and trash/.
- Project mode JSON sync now includes context_cost (was nil)
- Server handler respects symlink mode (skips include/exclude filters)
- checkBudget reports all targets exceeding threshold (not just worst)
- Budget warnings include target name in CLI and UI output
- ConfigPage indentation restored to original 2-space style
The assistant panel already shows field documentation via JSON schema.
A static reference card is redundant and breaks the page's interaction
pattern of cursor-driven contextual help.