# Tagsmith

> Opinionated Git tag and SemVer release-tag manager.

Declarative release intent for single-target repositories and monorepos. Interactive for humans, deterministic for automation.

## Table of Contents

### Getting started

- [Tagsmith documentation](https://tagsmith.site/docs.md): Read the Tagsmith documentation for SemVer Git tag creation, annotated release tags, monorepo targets, CI validation, and JSONC configuration.
- [Get started with Tagsmith SemVer Git tags](https://tagsmith.site/docs/getting-started.md): Install Tagsmith, create a .tagsmith.jsonc config, preview the next SemVer release tag, create an annotated Git tag, and validate it in CI.
- [Set up Tagsmith with an AI coding agent](https://tagsmith.site/docs/setup-with-ai.md): Use the generated Tagsmith LLM documentation to let an AI coding agent configure release targets, tag patterns, channels, and CI validation safely.

### Concepts

- [Tagsmith release targets, channels, and versions](https://tagsmith.site/docs/concepts.md): Learn the Tagsmith mental model for release targets, stable and prerelease channels, SemVer bumps, dependency gates, managed tags, and interactive flows.
- [Git tag patterns for Tagsmith releases](https://tagsmith.site/docs/tag-patterns.md): Configure Tagsmith tagPattern templates for single-target repos and monorepos, including SemVer captures, target names, ambiguity rules, and Git ref safety.
- [SemVer version bumps and prerelease channels](https://tagsmith.site/docs/versioning.md): Understand how Tagsmith resolves SemVer major, minor, patch, and prerelease bumps across stable channels, alpha, beta, rc flows, and explicit versions.
- [Interactive release tagging flows in Tagsmith](https://tagsmith.site/docs/interactive.md): Understand when Tagsmith prompts in a TTY, how interactive init, targets, validate, and tag flows work, and how every prompt maps to explicit CLI flags.

### Reference

- [Tagsmith JSONC configuration reference](https://tagsmith.site/docs/configuration.md): Reference every Tagsmith .tagsmith.jsonc field, including git settings, defaults, targets, channels, tag patterns, tag messages, and SemVer validation rules.
- [Tagsmith preflight checks before tagging and validation](https://tagsmith.site/docs/preflight.md): Review the Git, config, target, tag, working tree, remote tag, and validation checks Tagsmith runs before creating or accepting release tags.
- [Git safety model for annotated release tags](https://tagsmith.site/docs/git-safety.md): See how Tagsmith safely creates annotated Git tags without fetching, checkout, merging, branch mutation, tag overwrites, or rollback on push failure.
- [Tagsmith JSON, GitHub output, and human CLI output](https://tagsmith.site/docs/output.md): Learn Tagsmith output modes for human CLI text, pretty JSON, GitHub Actions outputs, raw init templates, exit codes, color rules, and error behavior.
- [Tagsmith CLI error catalogue and fixes](https://tagsmith.site/docs/errors.md): Look up Tagsmith CLI errors for parsing, repo discovery, config validation, Git safety, release planning, tag validation, push verification, and GitHub outputs.

### Commands

- [tagsmith init command reference](https://tagsmith.site/docs/cli/init.md): Reference the tagsmith init command for creating, overwriting, previewing, and customizing the .tagsmith.jsonc release configuration template.
- [tagsmith tag command reference](https://tagsmith.site/docs/cli/tag.md): Reference the tagsmith tag command for resolving SemVer versions, creating annotated Git tags, dry-running releases, pushing tags, and using interactive flows.
- [tagsmith validate command reference](https://tagsmith.site/docs/cli/validate.md): Reference the tagsmith validate command for checking managed Git tags, SemVer channel shape, dependsOn gates, JSON output, and GitHub outputs.
- [tagsmith list command reference](https://tagsmith.site/docs/cli/list.md): Reference the tagsmith list command for inspecting local and remote Git tags that match the current Tagsmith configuration.
- [tagsmith targets command reference](https://tagsmith.site/docs/cli/targets.md): Reference the tagsmith targets command for listing configured release targets, validating target paths, and emitting machine-readable JSON target metadata.

### Continuous integration

- [GitHub Actions release tag validation with Tagsmith](https://tagsmith.site/docs/ci.md): Use Tagsmith in GitHub Actions to validate annotated SemVer release tags, export release facts to $GITHUB_OUTPUT, and gate publish or deploy jobs safely.