sx

# sx - Coding Agent Guide

Your team's private npm for AI assets - skills, MCP configs, commands, and more.

## Quick Commands

```bash
make build          # Build binary to ./dist/sx
make test           # Run tests
make format         # Format code
make lint           # Run linter
make prepush        # Format + lint + test + build (run before claiming done)
```

## Before Reporting Work Complete

**ALWAYS run `make prepush` before claiming a task is finished.** CI runs
format, lint, tests, and build — if any of those fail locally, don't
tell the user the work is done.

## Testing Local Changes

After making code changes, build and test with:

```bash
make build && ./dist/sx <command>
```

## Tech Stack

- Go 1.25+
- cobra (CLI framework)
- TOML (config format)

## Key Specifications

- [Vault Spec](docs/vault-spec.md) - Vault structure and management
- [Manifest Spec](docs/manifest-spec.md) - sx.toml format (source of truth)
- [Lock Spec](docs/lock-spec.md) - Per-user resolved lock file format
- [Scoping](docs/scoping.md) - Overview of every install scope (org/repo/path/team/user/bot), links to per-scope docs
- [Permissions / RBAC](docs/rbac.md) - github vault: who can set scope (org-admins) and who can edit a skill (team-scope membership)
- [Vault copy](docs/copy.md) - `sx vault copy` cross-vault migration (assets, teams, bots, scopes, audit, usage)
- [Synced folders](docs/synced-folders.md) - Shared path vaults inside Dropbox/Drive/OneDrive/iCloud folders
- [Plugins](docs/plugins-spec.md) - Exposing vaults as Claude Code / Codex plugin marketplaces
- [Orgs](docs/orgs.md) - Org-scoped (global) installs
- [Repos](docs/repos.md) - Repo and path-scoped installs (monorepo patterns)
- [Teams](docs/teams.md) - Team management and team-scoped installs
- [Users](docs/users.md) - Single-user installs and self-only restriction
- [Bots](docs/bots.md) - Bot identities and bot-scoped installs
- [Audit log](docs/audit.md) - Mutation audit trail format and queries
- [Usage analytics](docs/stats.md) - `sx stats` dashboard and event format
- [Metadata Spec](docs/metadata-spec.md) - Asset metadata format and fields
- [MCP Spec](docs/mcp-spec.md) - MCP server tools (query)
- [Environment Variables](docs/environment-variables.md) - SX_CONFIG_DIR, SX_CACHE_DIR, and isolation recipes
- [GitHub Actions](docs/github-actions.md) - Installing from a private vault in CI (deploy keys, SX_SSH_KEY, SX_BOT)

## Development

- Format: `gofmt`
- Lint: `golangci-lint`
- Tests must pass with race detection
- Use conventional commit messages
- **NEVER run `git push` without explicit user permission**

## Releases

Tag and push to trigger automated release:

```bash
git tag v0.1.0
git push origin v0.1.0
```

GoReleaser builds for Linux/macOS/Windows and auto-generates changelog.