@ryanreh99/skills-sync 1.0.0

package/docs/agent-storage-map.md

@@ -0,0 +1,153 @@
+# Agent Storage Map (Validated)
+
+This document records the current source-of-truth findings for runtime storage and config behavior for:
+- Codex CLI (OpenAI)
+- Claude Code (Anthropic)
+- Cursor
+- Gemini CLI
+
+If a field is not clearly documented in official docs, it is marked **UNVERIFIED** and `skills-sync` uses a conservative default.
+
+## Codex CLI (OpenAI)
+
+### Config and MCP
+- User config: `~/.codex/config.toml` (Windows equivalent: `%USERPROFILE%\\.codex\\config.toml`)
+- Project config: `.codex/config.toml` (trusted projects)
+- MCP schema: TOML tables under `[mcp_servers.<name>]` with keys like:
+  - `transport`
+  - `command`, `args`, `env`, `env_vars`, `cwd` (stdio)
+  - `url`, `bearer_token_env_var`, `http_headers`, `env_http_headers` (HTTP)
+
+### Skills / discovery
+- Codex skills docs describe discovery from `.agents/skills` and other scopes.
+- `SKILL.md`-based folders are supported.
+
+### Precedence and env vars
+- Docs show user + project config and per-run overrides (`-c/--config`).
+- `CODEX_HOME` controls Codex home location.
+
+### Stability
+- MCP and skills are documented as first-class features (treated as stable for this repo).
+
+### Sources
+- https://developers.openai.com/codex/config-advanced
+- https://developers.openai.com/codex/mcp
+- https://developers.openai.com/codex/skills
+
+---
+
+## Claude Code (Anthropic)
+
+### Config and MCP
+- Settings files:
+  - User: `~/.claude/settings.json`
+  - Project: `.claude/settings.json`
+  - Local project override: `.claude/settings.local.json`
+- MCP config locations documented as:
+  - Main Claude config (primary): `~/.claude.json`
+  - Dedicated MCP file: `~/.claude/mcp_servers.json`
+  - Project scope: `.mcp.json`
+  - Precedence: when both user-level files are present, the main `~/.claude.json` takes priority over `~/.claude/mcp_servers.json`.
+
+### Skills / sub-agents discovery
+- Sub-agents:
+  - User: `~/.claude/agents/`
+  - Project: `.claude/agents/`
+- `~/.claude/skills` / `.claude/skills` are **UNVERIFIED** in Anthropic docs.
+  - This repo uses `.claude/skills` as a conservative compatibility path.
+
+### Precedence and env vars
+- Settings precedence is documented (managed > user/project tiers).
+- `CLAUDE_CONFIG_DIR` is documented for config/data location control.
+
+### Stability
+- Claude settings + MCP are documented.
+- Sub-agents are documented as primary feature.
+
+### Sources
+- https://docs.anthropic.com/en/docs/claude-code/settings
+- https://docs.anthropic.com/en/docs/claude-code/mcp
+- https://docs.anthropic.com/en/docs/claude-code/sub-agents
+
+---
+
+## Cursor
+
+### Config and MCP
+- MCP config:
+  - User: `~/.cursor/mcp.json`
+  - Project: `.cursor/mcp.json`
+- MCP schema uses JSON `mcpServers` objects with keys like `command`, `args`, `env`.
+
+### Skills / discovery
+- Cursor-native locations:
+  - `.agents/skills/`
+  - `.cursor/skills/`
+  - `~/.agents/skills/`
+  - `~/.cursor/skills/`
+- Compatibility loading (officially documented):
+  - `.claude/skills/`
+  - `.codex/skills/`
+  - `~/.claude/skills/`
+  - `~/.codex/skills/`
+- Discovery is **top-level only** (same constraint as Gemini). Nested skill namespaces require flat aliases at the skills directory root for reliable detection.
+
+### Precedence and env vars
+- Project vs global MCP files are documented.
+- Cursor CLI config has documented envs:
+  - `CURSOR_CONFIG_DIR`
+  - `XDG_CONFIG_HOME` (Linux/BSD)
+- MCP-specific env-override variable for config file location is **UNVERIFIED**.
+
+### Stability
+- MCP and skills pages are official docs pages.
+
+### Sources
+- https://cursor.com/docs/context/mcp
+- https://cursor.com/docs/context/skills
+- https://cursor.com/docs/context/rules
+- https://cursor.com/docs/cli/reference/configuration
+
+---
+
+## Gemini CLI (Google)
+
+### Config and MCP
+- Settings files:
+  - User: `~/.gemini/settings.json`
+  - Project: `.gemini/settings.json`
+- MCP config lives in `settings.json` under:
+  - `mcpServers` (server definitions)
+  - `mcp` (global MCP behavior settings)
+
+### Skills / sub-agents discovery
+- Skills discovery:
+  - `.gemini/skills/` and alias `.agents/skills/` (project)
+  - `~/.gemini/skills/` and alias `~/.agents/skills/` (user)
+  - discovery is path-local (`SKILL.md` or `*/SKILL.md`), so nested namespace trees require flatten/aliasing for reliable detection.
+  - documented precedence includes workspace over user over extension.
+- Custom agents/subagents:
+  - docs show `.gemini/agents/*.md` and `~/.gemini/agents/*.md`
+  - subagents are explicitly marked experimental.
+
+### Precedence and env vars
+- Settings precedence is explicitly documented.
+- `GEMINI_CLI_HOME` controls user config/storage root.
+
+### Stability
+- Settings/MCP/skills are documented.
+- Subagents/agent-mode area includes experimental labeling.
+
+### Sources
+- https://geminicli.com/docs/reference/configuration
+- https://geminicli.com/docs/tools/mcp-server/
+- https://geminicli.com/docs/cli/skills/
+- https://geminicli.com/docs/core/subagents/
+
+---
+
+## Conservative defaults used by this repo
+
+- `apply` manages **user-level targets only** by default.
+- Cursor adapter uses copy+aliases projection (same as Gemini) — skills are copied to `dist/.cursor/skills` with flat `vendor__*` aliases for any nested skill paths, then bound to `~/.cursor/skills` at apply time.
+- When schema/path behavior is ambiguous, docs are preserved in this file and implementation avoids destructive assumptions.

package/docs/architecture.md

@@ -0,0 +1,117 @@
+# Architecture
+
+## Design Principle
+- Internal model is stable.
+- External agent contracts are volatile.
+- Adapters are thin and mechanical.
+
+This repo keeps one canonical build artifact and projects to per-agent runtime shapes.
+
+## Pipeline
+1. Inputs in `workspace/`
+2. `build` creates canonical bundle + projections in `dist/`
+3. `apply` binds skills dirs and merges managed MCP entries into runtime targets
+4. `unlink` reverses managed bindings/entries
+
+## Canonical Artifact
+`~/.skills-sync/internal/common/` is the source of truth:
+- `bundle.json`
+- `skills/`
+- `mcp.json`
+
+## Projections
+Built from `common`:
+- `dist/common/skills`, `dist/common/mcp.json`
+- `dist/.codex/*`, `dist/.claude/*`, `dist/.cursor/*`, `dist/.copilot/*`, `dist/.gemini/*`
+
+## Internal Modules
+- Bundle builder: `internal/scripts/lib/bundle.mjs`
+- Build orchestration: `internal/scripts/lib/build.mjs`
+- Adapters:
+  - `internal/scripts/lib/adapters/codex.mjs`
+  - `internal/scripts/lib/adapters/claude.mjs`
+  - `internal/scripts/lib/adapters/cursor.mjs`
+  - `internal/scripts/lib/adapters/copilot.mjs`
+  - `internal/scripts/lib/adapters/gemini.mjs`
+  - `internal/scripts/lib/adapters/common.mjs`
+- Binding/apply/unlink: `internal/scripts/lib/bindings.mjs`
+- MCP managed merge: `internal/scripts/lib/mcp-config.mjs`
+- Validation: `internal/scripts/lib/doctor.mjs`
+
+## Runtime Write Policy
+- Skills: linked (Windows junction/symlink, macOS symlink).
+- MCP: merged under managed namespace `skills-sync__*`.
+- Unmanaged entries are preserved.
+
+## Link Behavior
+- Windows directories: junction, symlink fallback
+- Windows files: hardlink, copy fallback
+- macOS: symlink
+
+## Scope Defaults
+- Apply targets user-level locations by default.
+- Path contracts and verification notes live in:
+  - [agent-storage-map.md](agent-storage-map.md)
+
+## AI Contexts
+
+`skills-sync` builds one canonical bundle and projects it to each agent runtime contract.
+
+Canonical source:
+- `~/.skills-sync/internal/common/skills`
+- `~/.skills-sync/internal/common/mcp.json`
+- `~/.skills-sync/internal/common/bundle.json`
+
+### Codex
+- Projection:
+  - `dist/.codex/skills`
+  - `dist/.codex/vendor_imports/skills`
+  - `dist/.codex/config.toml`
+- Apply:
+  - skills dir binding
+  - managed MCP block in user config TOML (`skills-sync__*`)
+
+### Claude Code
+- Projection:
+  - `dist/.claude/skills`
+  - `dist/.claude/mcp.json`
+- Apply:
+  - skills dir binding
+  - managed MCP JSON entries under `mcpServers.skills-sync__*`
+
+### Cursor
+- Projection:
+  - `dist/.cursor/skills` (includes top-level `vendor__*` aliases for discoverability)
+  - `dist/.cursor/mcp.json`
+- Apply:
+  - skills dir binding
+  - managed MCP JSON entries under `mcpServers.skills-sync__*`
+- Cursor skills docs note native + compatibility discovery paths:
+  - `.agents/skills`, `.cursor/skills`, `~/.agents/skills`, `~/.cursor/skills`
+  - `.claude/skills`, `.codex/skills`, `~/.claude/skills`, `~/.codex/skills`
+
+### Copilot
+- Projection:
+  - `dist/.copilot/skills` (includes top-level `vendor__*` aliases for discoverability)
+  - `dist/.copilot/mcp-config.json`
+- Apply:
+  - skills dir binding
+  - managed MCP JSON entries under `mcpServers.skills-sync__*`
+
+### Gemini CLI
+- Projection:
+  - `dist/.gemini/skills` (includes top-level `vendor__*` aliases for discoverability)
+  - `dist/.gemini/vendor_imports/skills`
+  - `dist/.gemini/settings.json`
+- Apply:
+  - skills dir binding
+  - managed MCP JSON entries under `mcpServers.skills-sync__*`
+  - aliases are required because Gemini skill discovery is path-local (`SKILL.md` or `*/SKILL.md`)
+
+## Important Behavior
+- `build` regenerates all dist artifacts.
+- During `build`, MCP projection policy is controlled by `canOverride` in target manifests:
+  - `true`: projection can be regenerated from canonical MCP
+  - `false`: projection is seeded from local config and MCP sections are updated in place
+- `apply` consumes existing dist artifacts and updates runtime targets.
+- `doctor` validates bundle, projections, state, and managed MCP presence.

package/docs/changelog.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+- Added Copilot runtime target support:
+  - skills path: `~/.copilot/skills` (Windows: `%USERPROFILE%\\.copilot\\skills`)
+  - MCP config path: `~/.copilot/mcp-config.json` (Windows: `%USERPROFILE%\\.copilot\\mcp-config.json`)
+  - default target policy: `canOverride: true`
+- Wired Copilot through build/apply/unlink/detect/doctor flows.
+- Extended integration fixtures/tests to validate Copilot behavior.

package/docs/commands.md

@@ -0,0 +1,94 @@
+# Commands
+
+Use either:
+- `npm run <script> -- <args>`
+- `node internal/scripts/skills-sync.mjs <command> <args>`
+
+## Command Surface
+1. `init [--seed]`
+2. `build [--profile <name>] [--lock=read|write|refresh]`
+3. `apply [--profile <name>] [--build] [--dry-run]`
+4. `doctor [--profile <name>]`
+5. `detect`
+6. `detect [--format text|json] [--agents <comma-list>]`
+7. `unlink [--dry-run]`
+8. `list upstreams [--format text|json]`
+9. `list skills [--upstream <id>] [--ref <ref>] [--profile <name>] [--format text|json]`
+10. `list upstream-content [--upstream <id>] [--ref <ref>] [--profile <name>] [--format text|json]`
+11. `list profiles [--format text|json]`
+12. `list everything [--format text|json]`
+13. `profile show [name] [--format text|json]`
+14. `profile add-skill <name> --upstream <id> --path <repoPath> [--ref <ref>] [--dest-prefix <prefix>]`
+15. `profile remove-skill <name> --upstream <id> --path <repoPath> [--ref <ref>] [--dest-prefix <prefix>]`
+16. `profile add-mcp <name> <server> (--command <command> [--args <arg...> | --arg <arg>...] [--env <KEY=VALUE...>] | --url <url>)`
+17. `profile remove-mcp <name> <server>`
+18. `profile export [name] [--output <path>]`
+19. `profile import <name> --input <path> [--replace]`
+20. `agent inventory [--agents <comma-list>] [--format text|json]`
+21. `agent drift [--profile <name>] [--agents <comma-list>] [--dry-run] [--format text|json]`
+22. `upstream add <id> --repo <url> [--default-ref <ref>] [--type git]`
+23. `upstream remove <id>`
+24. `search skills [--upstream <id>] [--ref <ref>] [--profile <name>] --query <text> [--format text|json]`
+25. `search skills [--upstream <id>] [--ref <ref>] [--profile <name>] --interactive`
+26. `use <name>`
+27. `current`
+28. `ls`
+29. `new <name>`
+30. `remove <name>`
+31. `help`
+
+Unknown commands fail with:
+`Unknown command. See: skills-sync help`
+
+## Notes
+- `init`: scaffolds minimal workspace only (non-destructive).
+- `init --seed`: backs up existing workspace and copies seed content (no build).
+- `apply`: does not build unless `--build` is provided. If `--profile` is omitted, it uses the profile embedded in `~/.skills-sync/internal/common/bundle.json`.
+- `apply --dry-run`: prints planned bind/config operations without touching files or state.
+- `detect`: prints resolved target paths and support mode per agent.
+- `detect --agents`: limits output to selected agents (for example: `codex,claude`).
+- `doctor`: validates contracts, lock pins, dist projections, and bindings.
+- `unlink --dry-run`: previews removals without deleting bindings or MCP entries.
+- `list upstreams`: lists configured upstream repositories and default refs.
+- `list skills`: lists all skills (path + title) available under `skills/**/SKILL.md`. If `--upstream` is omitted, it lists across profile-derived refs (or all upstream defaults when no profile is provided).
+- `list upstream-content`: lists both skills and any discoverable upstream MCP manifests (`**/mcp/servers.json`) for selected upstream refs.
+- `list profiles`: same profile listing as `ls`, with optional JSON output.
+- `list everything`: prints every discovered profile plus its local/imported skills and MCP servers.
+- `profile show [name]`: shows one profile's local skills, imported skills, and MCP servers (defaults to current profile if omitted).
+- `profile add-skill` / `profile remove-skill`: edits `workspace/packs/<name>/sources.json` skill imports.
+- `profile add-mcp` / `profile remove-mcp`: edits `workspace/packs/<name>/mcp/servers.json`. For add, provide exactly one of `--command` or `--url` (`--env` entries use `KEY=VALUE` format and apply to `--command` only). Use repeated `--arg` for dash-prefixed command args, for example `--arg --stdio`.
+- `profile export`: exports profile pack config and local skill files to JSON for migration.
+- `profile import`: imports exported profile config into local workspace.
+- `agent inventory`: inspects installed skills and MCP servers per detected agent, including parse issues.
+- `agent drift --dry-run`: compares profile-expected skills/MCP against installed agent state without mutating files.
+- `agent drift`: reconciles drift by promoting detected extra MCP servers into the selected profile, then rebuilds and applies across detected agents before reporting final drift.
+- `upstream add` / `upstream remove`: edits `workspace/upstreams.json`. Removing also prunes matching lock pins from `workspace/upstreams.lock.json`.
+- `search skills` (non-interactive): filters skills by keyword matched case-insensitively against skill path and title.
+- `search skills --interactive`: prompt-based search loop for ad-hoc exploration.
+- `use <name>`: writes `{ "defaultProfile": "<name>" }` to `workspace/config.json`. After this, `--profile` can be omitted from `build`, `apply`, and `doctor`.
+- `current`: prints the current default profile name from `workspace/config.json`.
+- `ls`: lists all profiles found in `workspace/profiles/` and `internal/seed/profiles/`, marking the default with `->`.
+- `new <name>`: scaffolds a new profile JSON and pack directory under `workspace/` (non-destructive).
+- `remove <name>`: deletes `workspace/profiles/<name>.json` and clears the default if it matched. Pack directory is preserved.
+
+## Default Profile (`workspace/config.json`)
+`--profile` is optional on `build`, `apply`, and `doctor`. When omitted, the CLI reads `defaultProfile` from `workspace/config.json`.
+
+Set it once:
+```bash
+skills-sync use personal
+# or edit workspace/config.json directly:
+# { "defaultProfile": "personal" }
+```
+
+Then omit `--profile` everywhere:
+```bash
+skills-sync build
+skills-sync apply
+skills-sync doctor
+```
+
+## Lock Modes (`build`)
+- `write` (default): writes missing pins.
+- `read`: never writes lockfile; fails when required pins are missing.
+- `refresh`: refreshes pins for all refs used by the selected profile.

package/docs/contracts.md

@@ -0,0 +1,112 @@
+# Contracts
+
+## Inputs
+
+### Profile
+Path:
+- `workspace/profiles/<name>.json`
+
+Schema:
+- `internal/contracts/inputs/profile.schema.json`
+
+Shape:
+```json
+{ "name": "personal", "packPath": "workspace/packs/personal" }
+```
+
+### Pack Manifest
+Path:
+- `<pack>/pack.json`
+
+Schema:
+- `internal/contracts/inputs/pack-manifest.schema.json`
+
+### Pack Sources
+Path:
+- `<pack>/sources.json`
+
+Schema:
+- `internal/contracts/inputs/pack-sources.schema.json`
+
+Shape:
+```json
+{ "imports": [] }
+```
+
+### MCP Servers Input
+Path:
+- `<pack>/mcp/servers.json`
+
+Schema:
+- `internal/contracts/inputs/mcp-servers.schema.json`
+
+Shape:
+```json
+{
+  "servers": {
+    "stdio-server": { "command": "...", "args": [], "env": { "KEY": "VALUE" } },
+    "http-server": { "url": "https://example.com/mcp" }
+  }
+}
+```
+
+### Upstreams + Lock
+- `workspace/upstreams.json` (fallback `internal/starter/upstreams.json`)
+- `workspace/upstreams.lock.json`
+
+Schemas:
+- `internal/contracts/inputs/upstreams.schema.json`
+- `internal/contracts/state/upstreams-lock.schema.json`
+
+## Runtime Targets
+
+Schema:
+- `internal/contracts/runtime/targets.schema.json`
+
+Required top-level keys:
+- `codex`
+- `claude`
+- `cursor`
+- `copilot`
+- `gemini`
+
+Per-tool target fields:
+- `skillsDir`: runtime skills directory target
+- `mcpConfig`: runtime MCP config target
+- `canOverride` (boolean): build projection policy for MCP config
+  - `true`: dist MCP projection can be generated directly from canonical bundle
+  - `false`: build reads existing local config (if present) and only replaces MCP sections
+
+## Build Contract
+
+Canonical artifact:
+- `~/.skills-sync/internal/common/bundle.json`
+- `~/.skills-sync/internal/common/skills/`
+- `~/.skills-sync/internal/common/mcp.json`
+
+Schema:
+- `internal/contracts/build/bundle.schema.json`
+
+`~/.skills-sync/internal/common` is authoritative.  
+All other `dist/*` paths are projections.
+
+## Projection Contract (Current)
+
+Primary projections:
+- `dist/common/*`
+- `dist/.codex/*`
+- `dist/.claude/*`
+- `dist/.cursor/*`
+- `dist/.copilot/*`
+- `dist/.gemini/*`
+
+## Runtime Mutation Contract
+
+`apply` behavior:
+- skills directories are linked where supported
+- MCP config is merged under `skills-sync__*` namespace
+- unmanaged user entries are preserved
+
+`unlink` behavior:
+- removes managed links
+- removes managed MCP namespace entries only

package/docs/homebrew.md

@@ -0,0 +1,46 @@
+# Homebrew
+
+## Install (users)
+Use this repository as a tap:
+
+```bash
+brew tap ryanreh99/skills-sync
+brew install ryanreh99/skills-sync/skills-sync
+```
+
+## Publish/Update (maintainers)
+This formula installs a release tarball produced by `npm pack`, with bundled runtime dependencies.
+
+1. Bump `package.json` version.
+2. Run release checks:
+   ```bash
+   npm ci
+   npm run prepublishOnly
+   ```
+3. Build the tarball:
+   ```bash
+   npm pack
+   ```
+   Example output: `skills-sync-1.0.0.tgz`
+4. Regenerate the formula with the release URL and local tarball hash:
+   ```bash
+   npm run brew:formula -- \
+     --url https://github.com/ryanreh99/skills-sync/releases/download/v1.0.0/skills-sync-1.0.0.tgz \
+     --tarball ./skills-sync-1.0.0.tgz
+   ```
+5. Commit `Formula/skills-sync.rb` (and any version/changelog updates) to the repository.
+6. Create/publish GitHub release tag `v<version>`.
+7. Upload the same `skills-sync-<version>.tgz` file from step 3 to that release.
+8. Optionally publish to npm:
+   ```bash
+   npm publish
+   ```
+
+If you already published to npm and want to generate directly from the npm tarball:
+
+```bash
+npm run brew:formula
+```
+
+The default URL for `npm run brew:formula` is:
+`https://registry.npmjs.org/<name>/-/<name>-<version>.tgz`

package/docs/quickstart.md

@@ -0,0 +1,14 @@
+# Quickstart
+
+## Minimal Setup
+1. `npm i -g @ryanreh99/skills-sync`
+2. `npx @ryanreh99/skills-sync`
+3. `skills-sync init --seed`
+4. `skills-sync use personal`
+5. `skills-sync build`
+6. `skills-sync apply`
+7. `skills-sync doctor`
+
+## Next
+- Main guide: - [user-guide.md](user-guide.md)
+- Full command reference: - [commands.md](commands.md)

package/docs/roadmap.md

@@ -0,0 +1,5 @@
+# Future Plans
+
+This document tracks planned roadmap items that are not implemented yet.
+
+No pending roadmap items right now.

package/docs/security.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Credential Handling
+
+- Never commit tokens, secrets, credentials, or private endpoints to this repository.
+- Keep real profile packs and machine-specific overrides in `workspace/` only.
+- Keep upstream clone cache data in `upstreams_cache/` only.
+- Store authentication material in environment variables consumed by MCP server commands.
+
+## Repository Safety Expectations
+
+- `examples/` must remain secret-free.
+- `manifests/` and `schemas/` must remain secret-free.
+- `dist/`, `workspace/`, and `upstreams_cache/` are generated/local and ignored by git.
+
+## Prohibited Content
+
+Do not commit any of the following:
+
+- API keys or bearer tokens
+- OAuth client secrets
+- username/password credentials
+- personal/private internal endpoints
+- `.env` files containing sensitive data
+
+## Reporting
+
+If a secret is committed accidentally:
+
+1. Revoke or rotate the secret immediately.
+2. Remove it from repository history.
+3. Re-run `doctor` and verify all examples/manifests remain clean.