# Getting started This tutorial cuts a real release of a small repo using only `tarsi-serve` — install, wire check, plan, dry-run, release, verify. The repo should use conventional commits. ## 1. Install `tarsi-serve` There is **no `tarsi` CLI** — the surface is `tarsi-serve`, an ndjson ops binary with a one-shot front door. It ships as a tamias pack (`libraries/tarsi`, `type: files` declaring `tarsi-serve` as a `tools/bin//` payload bin): ```bash # From a tarsi checkout: cargo xtask pack # release-build → libraries/tarsi/tools/bin// tamias install ./libraries/tarsi # deploys `tarsi-serve` onto PATH ``` Dev shortcut without tamias: `cargo xtask install` puts a release `tarsi-serve` in `~/.local/bin`. ## 2. Check the wire ```bash tarsi-serve manifest # → {"name":"tarsi-serve","version":"…","ops":["manifest","profiles","plan","changelog","notes","release"]} ``` Two modes: no args = ndjson JSON-lines loop on stdio (`{"op": …, "params": …}` in, `{"ok": …, "result"|"error"}` out); `tarsi-serve [--dir D] [--set k=v]… [--yes|--dry-run]` = one-shot argv — `--yes` maps to `dry_run: false`, `--dry-run` forces the default. See [Drive tarsi-serve ops](/how-to/use-serve-ops) for the full surface. ## 3. Prepare the repo The repo needs a `tarsi.toml`. The minimal useful one: ```toml # tarsi.toml [publish.crates] enabled = false [publish.ghreleases] enabled = false ``` Tag-only releases are the org convention (ADR-0004); without the `enabled = false` lines both publish targets default to on. Units default to cargo workspace members — for a non-cargo repo, declare them explicitly (see [Write a tarsi.toml](/how-to/write-tarsi-toml)). Make sure the history you want released is conventional: ```bash git log --oneline # feat(api): add retries → minor bump # fix(core): handle empty body → patch bump # chore: tidy imports → no release on its own ``` ## 4. Plan ```bash tarsi-serve plan --dir . ``` Read the result. Each unit in `plan.units` carries: * `spec` — resolved unit (name, path, tag format, publish targets) * `bump` — `major` / `minor` / `patch` / `none` * `new_version` — the version the bump would write * `tag` — e.g. `my-unit-v1.2.0` * `releases` — whether this unit actually releases * `changelog_markdown` — the rendered changelog section * `commits` — how many commits were attributed `plan.unattributed` lists commits that matched no unit's paths — repo-root files land there. `plan.steps` is the mutation sequence `release` would run. Nothing has been written. This is the review gate — always `plan` before `release`. ## 5. Preview the notes ```bash tarsi-serve changelog --dir . # per-unit {unit, version, tag, markdown} tarsi-serve notes --dir . # concatenated release notes ``` ## 6. Dry-run the release ```bash tarsi-serve release --dir . ``` `release` is **dry-run by default** — this executes the full plan and runs every publish target in dry-run mode, reporting what *would* happen, and writes nothing. Equivalently over ndjson: ```json {"op":"release","params":{"dir":".","dry_run":true}} ``` ## 7. Release for real Only after the plan looks right and a human approves: ```bash tarsi-serve release --dir . --yes ``` `--yes` is `dry_run:false`. The mutation phase, in order: 1. Write `CHANGELOG.md` sections per releasing unit (created files are tracked for rollback). 2. Bump versions in manifests via `toml_edit` (comments preserved). 3. Stage only the touched files — `CHANGELOG.md`/`Cargo.toml` per unit plus root manifests — never `git add -A`. 4. Commit `chore(release): bump versions`. 5. Tag each releasing unit (`{unit}-v{version}`). 6. **Push branch + tags before publishing** — GitHub Releases auto-creates tags at remote HEAD otherwise. 7. Run publish targets (crates.io, GitHub Releases) against the pushed commit. The result reports `steps_run`, per-target `publish` reports, and — on failure — `rolled_back` or a manual-cleanup note for partial publishes. ## 8. Verify ```bash git tag -l '*-v*' | tail git log --oneline -3 tarsi-serve plan --dir . # now: nothing to release ``` The latest-tag-per-unit range means a second `plan` finds no new commits since the tags you just pushed. ## What you now know * `tarsi-serve` is the whole surface: one-shot argv ops plus an ndjson loop, dry-run by default. * `plan` is the review gate — per-unit bump, version, tag, changelog, and the exact mutation sequence `release` would run. * `release --yes` mutates in order: changelogs → manifest bumps → staged commit → tags → push → publish — with rollback reporting. * Re-running `plan` after a release finds nothing new: latest-tag- per-unit ranges are the idempotency boundary. ## Next steps * Layer org conventions with a profile — [Author a release profile pack](/how-to/author-release-profile) * Tune attribution and overrides — [Write a tarsi.toml](/how-to/write-tarsi-toml) * Script it from an agent — [Drive tarsi-serve ops](/how-to/use-serve-ops) --- --- url: /tarsi/how-to.md --- # How-to guides * [Write a tarsi.toml](write-tarsi-toml.md) — units, publish targets, strategy tables * [Author a release profile pack](author-release-profile.md) — `type: tarsi` tamias packs * [Drive tarsi-serve ops](use-serve-ops.md) — the ndjson wire and one-shot argv --- --- url: /tarsi/how-to/write-tarsi-toml.md --- # Write a tarsi.toml `tarsi.toml` (or `tarsi.yaml`/`tarsi.yml` — YAML wins on ties) is the repo's release config. It is a plain [`tarsi_core::Config`](https://docs.rs) document — the full schema is in [reference/config](/reference/config); this page is the practical guide. ## Discovery `tarsi-config` resolves config through scarab-config discovery: 1. `$TARSI_CONFIG` — explicit file, the whole config (no layering) 2. `./tarsi.{yaml,yml,toml}` in the repo being released 3. `~/.config/tarsi/` When a [release profile](/how-to/author-release-profile) is active, loading becomes layered instead of first-match: ``` repo tarsi.* > profile tarsi.* > ~/.config/tarsi/ > defaults ``` Objects merge key-wise; repo keys win. ## The minimal file ```toml [release] strategy = "conventional" changelog_path = "CHANGELOG.md" diff_exclude = ["docs/**", "project/**", "*.md", ".github/**"] [publish.crates] enabled = false [publish.ghreleases] enabled = false ``` ## `[release]` — what gets released | key | default | meaning | | --- | --- | --- | | `units` | cargo workspace members | explicit unit list, or a units spec | | `tag_format` | `{unit}-v{version}` | tag template; `{unit}`/`{version}` expand | | `changelog_path` | `CHANGELOG.md` | changelog file spliced per unit | | `strategy` | `conventional` | release strategy — builtin name or inline rules table | | `default_bump` | none | fallback bump when inference finds nothing | | `diff_exclude` | `[]` | path globs stripped from commits before attribution (a commit left with no paths is dropped) | | `unit_overrides` | `{}` | per-unit overrides, keyed by unit name | | `sync_refs` | `{rules:[]}` | rewrite pack/doc version refs into the release commit | ### Units Omit `units` entirely for cargo workspaces — every workspace member becomes a release unit resolved from its manifest. To declare units explicitly (non-cargo repos, filtered members), use the `units` spec — see `tarsi_core::unit::UnitsSpec` for the shape (`Explicit { units }` with per-unit `name`/`path`/`tag_format`/`publish`/`bump` fields). ### Overrides ```toml [release.unit_overrides.tarsi-xtask] skip = true [release.unit_overrides.my-lib] bump = "patch" # force a bump regardless of inference tag_format = "lib-{version}" publish = ["crates-io"] # restrict targets for this unit ``` `skip = true` drops the unit from planning entirely (e.g. a lib that versions with its parent). Override `bump`/`tag_format`/`publish` merge onto the resolved spec; per-unit values always beat repo-level defaults. `diff_exclude` matters more than it looks: docs and config churn would otherwise attribute commits to units and trigger spurious releases. The org profile excludes `docs/**`, `project/**`, `*.md`, `.github/**`. Matching paths are stripped from each commit before attribution; a commit left with no paths is dropped entirely. ### Release strategy `strategy` is the release *policy* as data — bump inference and changelog sectioning (P-030). Name a builtin or write an inline table; absent means `conventional`: ```toml strategy = "semantic-release-angular" # builtin preset strategy = "keep-a-changelog" # KaC sections, same bump rules # …or fully custom: [release.strategy.bump] fallback = "patch" [[release.strategy.bump.rules]] type = "feat" # raw type token — "deps"/"i18n" work too bump = "major" [release.strategy.changelog] [[release.strategy.changelog.sections]] key = "features" heading = "Features" [[release.strategy.changelog.sections.rules]] type = "feat" ``` Bump rules fold **max-match** (highest `bump` wins per commit, then per unit); changelog sections are **first-match** in table order, which is also render order. `default_bump` fills `strategy.bump. fallback` when the strategy doesn't set one. Builtins: `conventional` (default), `semantic-release-angular` (the commit-analyzer angular preset), and `keep-a-changelog` (the keepachangelog.com section layout over the conventional bump rules — `### Added`/`Changed`/`Deprecated`/`Removed`/`Fixed`/ `Security`; full mapping in [reference/config](/reference/config#keep-a-changelog)). Full schema in [reference/config](/reference/config#release-strategy); the resolved strategy echoes on `plan` results as `plan.strategy`. ### Syncing version refs (`sync_refs`) Repos that ship a tamias pack usually keep `name@version` refs in docs and the pack manifest's `version:` in lockstep with releases. `[release.sync_refs]` does that rewrite inside the pipeline — before the release commit, so refs land in the tagged tree: ```toml [release.sync_refs] rules = [ { files = ["libraries/myco/tamias.yaml"], find = "(?m)^version: \"{old}\"", replace = "version: \"{new}\"" }, { files = ["README.md", ".agents/skills/myco/SKILL.md"], find = "myco@{old}", replace = "myco@{new}" }, ] ``` `{old}`/`{new}` are the releasing units' shared old/new version. Rules skip (with a reported reason) on mixed-version plans, are idempotent, and show up as `status:"dry-run"` + `changed_files` in a `bump`/`release` dry-run. Full semantics in [reference/config](/reference/config#release-sync_refs). With rules configured, `scripts/release.sh` shrinks to a bare `tarsi-serve release --dir . --yes`. ## `[publish.*]` — where releases go Both targets default to **enabled** — set `enabled = false` for tag-only repos (the org convention). ```toml [publish.crates] enabled = true retry_429 = true # backoff on crates.io rate limits max_attempts = 5 [publish.ghreleases] enabled = true token_env = "GITHUB_TOKEN" # env var NAME — never a value repo = "owner/name" # optional; defaults to origin remote assets = ["dist/{unit}-{version}-*"] ``` * `token_env` is a secret **name** resolved via the environment/cuora at publish time; values never appear in config or logs. * `assets` are repo-root-relative globs; `{unit}`/`{version}` expand per releasing unit. Magic patterns matching nothing are skipped; literal paths must exist. `[publish] dry_run = true` exists in the schema but the serve surface already dry-runs `release` by default — prefer `dry_run:false` at the op level. ## Selecting a profile ```toml profile = "9aia-release" ``` …or per-invocation, which beats both the config key and `$TARSI_PROFILE`: ```bash tarsi-serve plan --dir . --set profile=9aia-release TARSI_PROFILE=9aia-release tarsi-serve plan --dir . ``` A named-but-missing profile is a hard error — releasing under silent defaults would surprise. ## Workspace-version caveat Units whose manifests use `version.workspace = true` share one version file: the bump is last-writer-wins across releasing units. Keep workspaces in lockstep or give units explicit versions until per-unit workspace versions exist (org ledger ADR-0003, decision 4). --- --- url: /tarsi/how-to/author-release-profile.md --- # Author a release profile pack Release profiles are tamias content packs of `type: tarsi` — the org's conventions (`9aia-release` in `libraries/9aia-release`) ship this way so every repo can layer them under its own `tarsi.toml`. ## The `type: tarsi` manifest contract ```yaml # tamias.yaml name: my-release-profile version: "0.1.0" type: tarsi description: >- Human label for the profile — surfaced by the `profiles` op. ``` Payload contract (validated by `tamias-driver-tarsi` at install): * Payload root MUST carry `tarsi.{yaml,yml,toml}` — a plain `tarsi_core::Config` document. **No `[profile]` table**: `profile = "…"` is the *selector* key a consumer writes, not something the pack carries. * Extra files may ride along (`styleguide.md`, commit maps, …); consumers resolve them relative to the profile dir. * `description` in `tamias.yaml` is the profile's label; an optional top-level `description` in `tarsi.toml` also works for dir-only profiles. ## The profile `tarsi.toml` Keep it to *conventions* — repo-specific overrides belong in the repo's own `tarsi.toml` (repo keys always win). `9aia-release` is the reference: ```toml [release] strategy = "conventional" # P-030: builtin name or inline rules table changelog_path = "CHANGELOG.md" diff_exclude = ["docs/**", "project/**", "*.md", ".github/**"] tag_format = "{unit}-v{version}" [publish.crates] enabled = false # org: crates.io is tamias-only (ADR-0004) [publish.ghreleases] enabled = false # org: tag-only releases ``` ## How profiles resolve `tarsi-config` discovery order for a named profile: 1. `--set profile=` on the op (highest) 2. `$TARSI_PROFILE` 3. `profile = ""` in the repo's config Profile *directories* are found in this order (`find_dir`): 1. `$TARSI_PROFILES_DIR` / `~/.config/tarsi/profiles//` — unversioned dir profiles (dev/pinned) 2. The tamias store — every `/name@label/` carrying a `tarsi.*`, newest version label wins (the store commit *is* the placement — the driver validates, it does not copy) Layering with a profile active: ``` repo tarsi.* > profile tarsi.* > ~/.config/tarsi/ > defaults ``` ## Ship it `tamias-driver-tarsi` (`crates/tarsi-driver`) is the content driver. `cargo xtask pack` stages a release build into `libraries//drivers/bin//`, and tamias registers bundled drivers *before* dispatching install — so: ```bash cargo xtask pack tamias install --allow-drivers ./libraries/my-release-profile ``` self-provisions the driver and lands the profile in the store, versioned by label. Verify resolution: ```bash tarsi-serve profiles # lists installed profiles tarsi-serve plan --dir . --set profile=my-release-profile ``` The driver's `status` verb reports which dir `find_dir` picks for a name and from which source; `uninstall` removes `profilesDir` copies (the store entry itself is dropped by tamias). ## Gotchas * **Dir profiles shadow store versions.** `~/.config/tarsi/profiles/` is searched first and carries no version — a stale copy there wins over every store version, including ones `tamias remove` dropped. The driver only writes there when `profilesDir` is configured (opt-in escape hatch). * **Unsafe names rejected.** Profile names are validated (`safe_name`) — stick to lowercase slug names like `9aia-release`. * **No silent fallback.** Naming a missing profile errors the op; there is no "profile not found → defaults" path. --- --- url: /tarsi/how-to/use-serve-ops.md --- # Drive tarsi-serve ops Every tarsi surface is an op on `tarsi-serve` — no CLI verbs, no `--json` flag. This page covers both transports. ## One-shot mode ```bash tarsi-serve --dir [--set key=value]… [--yes|--dry-run] ``` `hypha-serve-cli` parses args into the op's `params`, dispatches, and prints the result JSON. Exit 0 on `ok:true`, 1 otherwise. ```bash tarsi-serve manifest tarsi-serve profiles tarsi-serve plan --dir . tarsi-serve plan --dir . --set profile=9aia-release --set range=HEAD~5..HEAD tarsi-serve release --dir . --yes # the only mutating call ``` Flag mapping: * `--set k=v` → `params[k] = "v"` (strings; repeat for multiple) * `--yes` → `params.dry_run = false` * `--dry-run` → `params.dry_run = true` (the default anyway) ## ndjson service mode ```bash tarsi-serve # no args — loop on stdio ``` One request per line, one response per line: ```json {"op":"manifest","params":{}} {"ok":true,"result":{"name":"tarsi-serve","version":"0.1.0","ops":[…]}} {"op":"release","params":{"dir":".","dry_run":true}} {"ok":true,"result":{"dry_run":true,"plan":{…},"publish":[…]}} ``` Errors come back as `{"ok":false,"error":"…"}` — including release failures, which also carry the partial `result` (plan, steps run, rollback report) for inspection. This is the wire peregrin campaigns and agents use; `tarsi-serve` is a composition root only — orchestration and UI live in the callers. ## Params reference Common params (all ops accept `dir`, default `.`): | param | type | meaning | | --- | --- | --- | | `dir` | string | repo being released | | `profile` | string | `type: tarsi` profile name (beats `$TARSI_PROFILE` and config `profile`) | | `range` | string | explicit rev range e.g. `"HEAD~5..HEAD"` — overrides since-last-tag for **every** unit | | `dry_run` | bool | `release` only; **default `true`** — mutation needs `false` | ## The safe sequence ```text manifest → profiles → plan → changelog → notes → release(dry_run:true) → release(dry_run:false) ``` Rules of thumb: * **Always `plan` before `release`.** The plan is the review gate. * **`dry_run:false` is the `--yes` equivalent** — get explicit human or campaign approval first; never run it against a repo you haven't planned. * **`range` is a debugging tool**, not a release mechanism — it applies one range to all units and bypasses per-unit tag ranges. * On failure, read `rolled_back` (clean undo) vs the manual-cleanup note (a publish target succeeded before another failed — the tag stays, live releases must not be orphaned). ## Calling from code `tarsi-serve` is a lib too: `tarsi_serve::dispatch(&GitVcs, &Request)` takes an injected `lasius_vcs::Vcs`, which is how `tarsi-testkit`'s conformance suite exercises the ops against fixture repos without a process. --- --- url: /tarsi/explanation.md --- # Explanation * [Architecture](architecture.md) — the ops wire, ports, where tarsi sits * [Release semantics](release-semantics.md) — dry-run default, bump inference, per-unit tags, ordering, rollback (ADR-0003) * [Concepts](concepts.md) — units, strategies, profiles, the wire * [Boundaries](boundaries.md) — owns / doesn't-own, neighbors named * [Decisions](decisions.md) — ADR-lite: decision → alternative → consequence --- --- url: /tarsi/explanation/architecture.md --- # Architecture Tarsi is the org's **release plane**: one pure domain core, a config loader, an ops wire, a publish port — and nothing else. It answers questions about releases; it never decides *when* to release or *who* approves. ``` caller (human, agent, peregrin campaign, scripts/release.sh) │ ndjson {"op": …, "params": …} or one-shot argv ▼ tarsi-serve ────────── hypha-serve-cli (shared arg→params shim) │ │ │ plans · bumps · │ tarsi.toml / type: tarsi profiles │ changelogs · tags │ (scarab-config FileSource/Layered) ▼ ▼ tarsi-core (pure) tarsi-manifest (Cargo.toml scan/patch) │ ▼ lasius-vcs ── git history, tags, push (tarsi-core never touches git) │ ▼ tarsi-publish port ── crates / ghreleases / dryrun impls ``` ## The pieces * **`tarsi-core`** — pure release domain: plans, units, semver bumps, commit classification, changelog rendering. No I/O. * **`tarsi-manifest`** — Cargo manifest scanning: workspace members → `ReleaseUnitSpec`, version reads/writes via `toml_edit`. * **`tarsi-config`** — `tarsi.toml`/`.yml` loading (scarab-config) plus `type: tarsi` profile-pack resolution. * **`tarsi-serve`** — the ops surface: `manifest` / `profiles` / `plan` / `changelog` / `notes` / `check` / `schema` / `bump` / `tag` / `publish` / `release`. No `tarsi` CLI exists. * **`tarsi-publish`** + `-crates` / `-ghreleases` / `-dryrun` — the publish port and per-forge impls. * **`tarsi-driver`** — `tamias-driver-tarsi`: the `type: tarsi` pack driver, plus a read-only pavo view. * **`tarsi-testkit`** — conformance fixtures + golden corpus. ## The ops wire Two modes over the same ops: no args = ndjson JSON-lines on stdio; ` [--dir D] [--set k=v] [--yes|--dry-run]` = one-shot argv via the shared `hypha-serve-cli` shim. `release`-family ops are **dry-run by default** — mutation requires `dry_run: false` (`--yes`). Humans, agents, and peregrin campaigns speak identical wire; there is deliberately no `tarsi-llm`. ## Profiles are packs Org release conventions ship as `type: tarsi` tamias packs (`libraries/9aia-release`) — layered config, versioned by the tamias store. `tamias-driver-tarsi` validates and installs them; `tarsi-config` resolves the layers through scarab-config's `FileSource`/`LayeredFileSource`. ## Where it sits In the org's layering — **tamias** (package & content manager) → **engines** (myco records, kuda code maps, mimus proofs, sepia sessions, sturn coordination, hypha substrate, cicada schedules, cypera docs, scarab config, peregrin orchestration) → **surfaces** (pavo views, MCP fronts). Tarsi sits at the **release plane beside the engines**: every repo's `scripts/release.sh` is a thin shim over `tarsi-serve`, org conventions ride tamias profile packs, and peregrin's `libraries/release` campaign drives the same ops — tarsi computes plans and mutations; orchestration decides when to run them. ## Deeper reads * [Release semantics](release-semantics.md) — the load-bearing rules (dry-run default, per-unit tags, ordering, rollback). * [Boundaries](boundaries.md) — owns / doesn't-own, neighbors named. * [Concepts](concepts.md) — units, strategies, profiles, the wire. * [Decisions](decisions.md) — ADR-lite. --- --- url: /tarsi/explanation/release-semantics.md --- # Release semantics The semantics below are load-bearing — they are pinned by **ADR-0003** in the org ledger (`9aia/project`, `project/adrs/0003-tarsi-release-semantics-plan-dry-run-bump-tag-manifest.md`). This page is the readable summary; the ADR is the contract. ## Dry-run is the default `tarsi-serve release` mutates only with `dry_run: false` — the `--yes` equivalent. Orchestration callers (peregrin campaigns, agents) opt in explicitly; anything probing a repo gets plans, never writes. This mirrors the org rule that service surfaces never mutate unless asked. ## Bump inference Conventional commits, attributed to units by path prefix. The inference itself is a **strategy** (P-030) — data-driven rules in `tarsi.toml`'s `[release] strategy`, defaulting to `conventional`: | commit | bump | | --- | --- | | `feat` | minor | | `fix` / `perf` | patch | | `!` / `BREAKING CHANGE:` | major | | `chore` / `docs` / `test` / … | none — no release | Bump rules fold **max-match** (a commit contributes the highest matching `bump`; the unit folds max across commits) against the commit's **raw type token** — arbitrary types like `deps` are nameable. Changelog sectioning is the same mechanism: ordered `sections[]`, first match wins, table order = render order. `semantic-release-angular` ships semantic-release's commit-analyzer angular preset as data; `keep-a-changelog` keeps the same bump rules but renders the six canonical keepachangelog.com sections (`### Added`/`Changed`/`Deprecated`/`Removed`/`Fixed`/`Security`) — KaC is a changelog layout, not a bump policy. Custom tables cover anything else short of non-semver versioning or plugin execution (the documented P-030 boundary). `spec.bump` (unit override or explicit unit spec) wins over inference; the strategy's `fallback` — filled by `release.default_bump` when unset — is the repo-wide fallback when inference finds nothing. Commits with empty path lists match every unit — conservative attribution. `release.diff_exclude` strips matching paths before attribution (a commit left with no paths is dropped). ## Per-unit tags, per-unit ranges Tag format is `{unit}-v{version}` per unit (`tamias-core-v0.4.2`), not repo-level `v{semver}`. Each unit's commit range is `{latest-tag-for-that-unit}..HEAD` — units release independently and only when their own paths changed. `params.range` overrides with one range for all units. ## Manifest mutation Versions are written via `toml_edit` (`tarsi-manifest`) — formatting and comments survive. Units with `version.workspace = true` bump `[workspace.package].version` instead: **all releasing units in such a workspace share one bump** (last-writer-wins today; per-unit workspace versions are a known limitation). ## Ordering and rollback The mutation phase is strictly ordered — changelogs → manifests → scoped `git add` (never `-A`) → `chore(release): bump versions` commit → per-unit tags → **push branch and tags** → publish. The push-before-publish order is load-bearing: GitHub Releases auto-creates `refs/tags/` at remote HEAD when the tag doesn't exist yet, which would pin the release to the pre-bump commit. Failure handling: * Any mutation failure → rollback undoes exactly what ran (remote tags deleted, branch reset, local commit/tags removed, created changelog files deleted) and the op reports `rolled_back`. * Publish failures roll back **only if nothing published** — once a target succeeded, deleting the tag would orphan a live release, so state is left and the report asks for manual cleanup. ## The LLM boundary There is deliberately no `tarsi-llm`. Changelog polish composes with **sepia**: the *caller* (peregrin node, agent) may prompt a sepia session with the rendered changelog. Conventional-commit output is the only in-repo path — deterministic by construction (ADR-0003, decision 6). ## Secrets Config carries env-var **names** (`token_env`, `CARGO_REGISTRY_TOKEN` via cuora secrets records) — never values. The cuora boundary holds end to end: names in manifests, values in the secrets broker. ## VCS ownership Git history, tags, and push go through `lasius-vcs` + `lasius-vcs-git` (org plan P-019). `tarsi-core` is pure — it sees only `Commit` values; every VCS call lives in `tarsi-serve` (and `tarsi-testkit` fixtures). New publish targets are a new `tarsi-publish-*` crate plus a `PublishTarget` variant; serve dispatch stays a match arm. --- --- url: /tarsi/explanation/concepts.md --- # Concepts The domain vocabulary, each term defined once. Field-level contracts live in [Reference](../reference/). ## Release unit One independently versioned thing — a cargo workspace member or an explicitly declared unit. Units resolve their own commit range (`{latest-tag-for-that-unit}..HEAD`) and release only when their paths changed. ## Op The unit of the `tarsi-serve` wire: `manifest`, `profiles`, `plan`, `changelog`, `notes`, `check`, `schema`, `bump`, `tag`, `publish`, `release`. One JSON object in, one result out — identical for humans, agents, and campaigns. ## Plan The computed, unwritten release: per-unit bump, `new_version`, tag, rendered changelog, publish targets, `steps` — plus `unattributed` commits. `plan` is the review gate; `release` executes it. ## Bump strategy The data-driven rule table mapping commit types to semver bumps — `[release] strategy` in `tarsi.toml`, defaulting to `conventional`. `semantic-release-angular` ships the angular preset; `keep-a-changelog` keeps the same bumps with KaC section names. `spec.bump` and `release.default_bump` override inference. ## Tag format `{unit}-v{version}` per unit (`tamias-core-v0.4.2`) — not a repo-level `v{semver}`. ## Profile pack A `type: tarsi` tamias package carrying org release defaults — layered config resolved by `tarsi-config` through scarab-config. Shipped via `libraries/9aia-release`. ## Publish target A forge destination — `crates` (crates.io), `ghreleases` (GitHub Releases), `dryrun`. Org repos keep both off: releases are tag-only and crates.io publishing is tamias-only. ## Dry-run The default for every `release`-family op: full plan + dry-run publish, zero writes. Mutation requires `dry_run: false` (`--yes`). ## Rollback Ordered mutation (changelogs → manifests → scoped add → bump commit → tags → push → publish) with exact undo: remote tags deleted, branch reset, created files removed. Publish failures roll back only if *nothing* published. --- --- url: /tarsi/explanation/boundaries.md --- # Boundary with tamias and peregrin tarsi owns **release semantics** — changelog → bump → tag → publish. Its neighbors own the layers around it: | neighbor | owns | tarsi's relation | | --- | --- | --- | | **tamias** | content distribution — fetch, store, cache, dispense; `type:` content drivers | release *profiles* are `type: tarsi` packs; `tamias-driver-tarsi` validates/installs them; the `tarsi-serve` binary itself ships as a `type: files` pack (`libraries/tarsi`) | | **peregrin** | orchestration — campaigns, multi-machine workflows | `libraries/release` bundle drives `tarsi-serve release --yes`; campaigns call the same ndjson ops humans and agents use | | **lasius** | git & workspace expertise — `lasius-vcs` port | all history/tag/push goes through `lasius-vcs` + `lasius-vcs-git`; `tarsi-core` never touches git | | **sepia** | session lifecycle | optional changelog polish — the caller may prompt a sepia session with rendered notes; no in-repo LLM path | | **cuora** | secrets broker | `token_env` names resolve through env/cuora; values never enter config, manifests, or logs | | **scarab** | config/template expertise | `tarsi.toml` discovery/layering is `scarab-config`'s `FileSource`/`LayeredFileSource`; tarsi-config is only the wiring | | **hypha** | distributed substrate | `hypha-serve-cli` is the shared one-shot arg→params shim every `*-serve` bin uses | ## What tarsi is not * **Not a CLI.** No `tarsi` binary, no verb tree — the surface is ops. (The legacy TypeScript changelog CLI under the README's bottom half is pre-rewrite reference only.) * **Not an orchestrator.** `tarsi-serve` composes ports and answers ops; scheduling, approval flows, and UI live in peregrin/pavo. * **Not a publisher of record for the org.** Org repos release tag-only; crates.io publishing is tamias-only and GitHub Releases are unused (ADR-0004). The `tarsi-publish-*` crates exist for external consumers who opt back in per-repo. * **Not a registry.** It reads git history and writes tags/manifests; it does not host anything. ## The dogfooding loop `tarsi`'s own `tarsi.toml` configures its release — units resolve from the cargo workspace, `tarsi-xtask` is skipped, both publish targets are off. Releasing tarsi itself is plan F of PL-014: a human or campaign decision, never an agent's. --- --- url: /tarsi/explanation/decisions.md --- # Decisions ADR-lite: the load-bearing decisions, each with the alternative it beat and the consequence it carries. The contracts are pinned by org-ledger ADRs — ADR-0003 (release semantics), ADR-0004 (tag-only * tamias publish), ADR-0005 (tarsi as the release plane), P-030 (strategy tables). ## Ops surface, not a CLI **Decision:** there is no `tarsi` binary — `tarsi-serve` exposes ndjson ops plus a one-shot argv front door. * *Alternative:* a conventional clap CLI like every other engine. * *Consequence:* humans, agents, and peregrin campaigns speak one wire; the surface is generatable (ops manifest → MCP/CLI tools). Cost: every interaction is a JSON round-trip, and `release.sh` shims exist per repo to keep the muscle memory. ## Dry-run is the default **Decision:** `release`-family ops mutate only with `dry_run: false` (`--yes`). * *Alternative:* mutate by default, flag to preview. * *Consequence:* agents and campaigns can probe any repo safely; the explicit opt-in mirrors "service surfaces never mutate unless asked" org-wide. ## Per-unit tags and ranges **Decision:** `{unit}-v{version}` tags; each unit's range is latest-tag-for-that-unit..HEAD. * *Alternative:* one repo-level `v{semver}`. * *Consequence:* units in a workspace release independently and only when their paths changed — the common case for polyrepos. ## Strategy as data, not code **Decision:** bump inference and changelog sectioning are data-driven rule tables (`[release] strategy`), not a plugin API. * *Alternative:* executable plugins / per-repo code. * *Consequence:* presets (`semantic-release-angular`, `keep-a-changelog`) ship as config; arbitrary types like `deps` are nameable. The documented P-030 boundary: non-semver versioning or plugin execution would need a different mechanism. ## No `tarsi-llm` **Decision:** changelog polish composes with sepia sessions at the *caller*; tarsi itself never calls a model. * *Alternative:* an in-repo LLM path for nicer notes. * *Consequence:* release semantics stay deterministic and auditable; the cuora/secrets boundary is untouched. ## Push before publish **Decision:** mutation order ends `push branch+tags → publish`. * *Alternative:* publish, then push. * *Consequence:* GitHub Releases auto-creates missing tags at remote HEAD — pushing first keeps the tag pinned to the bumped commit. Load-bearing, pinned by ADR-0003. --- --- url: /tarsi/reference.md --- # Reference * [Ops wire surface](ops.md) — every `tarsi-serve` op and its params * [tarsi.toml schema](config.md) — repo config fields * [Pack layout](pack-layout.md) — `libraries/` tamias packs * [Crates](crates.md) — the workspace crate map --- --- url: /tarsi/reference/ops.md --- # Ops wire surface `tarsi-serve` speaks ndjson JSON-lines: one `{"op": …, "params": …}` per line on stdin, one `{"ok": …, "result"|"error"}` per line on stdout — the same protocol shape as `sepia serve` / `tamias-driver` verbs. `tarsi-serve manifest` returns this list authoritatively. > Stage-wise note: granular per-stage ops may land as the surface > grows. The six ops below are the current stable contract; check > `manifest` for the live list before scripting against anything > newer. ## Ops ### `manifest` No params. Returns the service manifest: ```json {"name":"tarsi-serve","version":"0.1.0","ops":["manifest","profiles","plan","changelog","notes","release"]} ``` ### `profiles` No params (ignores `dir`). Returns every installed `type: tarsi` release profile: ```json {"profiles":[{"name":"9aia-release","version":"0.1.0","description":"…","source":"/path/to/dir"}]} ``` Discovery order: `$TARSI_PROFILES_DIR` / `~/.config/tarsi/profiles/` (dir profiles) then the tamias store (`name@label`, newest label wins). See [Author a release profile pack](/how-to/author-release-profile). ### `plan` Params: `dir?`, `profile?`, `range?`. Pure — computes, writes nothing. ```json { "specs": [ …resolved ReleaseUnitSpec… ], "plan": { "units": [ { "spec": { … }, "bump": "minor", "new_version": "0.3.0", "tag": "my-unit-v0.3.0", "releases": true, "changelog_markdown": "## [0.3.0] …", "commits": 4, "publish_targets": [{"target":"crates-io","enabled":false}] } ], "unattributed": [{"sha":"…","subject":"…"}], "steps": ["write-changelogs","bump-manifests","commit-bump","tag","push","publish"], "strategy": {"name":"conventional","resolved":{…rules…}} } } ``` `strategy` echoes the release strategy resolved from `[release] strategy` (P-030) — `name` is the builtin name or `"custom"` for inline tables; `resolved` is the full rule set that produced the bumps/changelogs. ### `changelog` Same params as `plan`. Returns only the releasing units' rendered notes: ```json {"changelogs":[{"unit":"my-unit","version":"0.3.0","tag":"my-unit-v0.3.0","markdown":"…"}]} ``` ### `notes` Same params. Concatenated `changelog_markdown` of all releasing units in plan order: ```json {"notes":"## [0.3.0] …\n## [1.1.0] …\n"} ``` ### `release` Same params plus `dry_run` (**default `true`**). Executes the plan. Dry-run result: ```json {"ok":true,"dry_run":true,"plan":{…},"steps_run":[],"publish":[{"target":…,"ok":…,"dry_run":true}…]} ``` Real result (`dry_run:false`): ```json { "ok": true, "dry_run": false, "plan": {…}, "steps_run": ["write-changelogs","bump-manifests","sync-refs","commit-bump","tag","push"], "publish": [ {"target":"github-release","ok":true,…} ], "sync_refs": {"status":"applied","old":"0.1.0","new":"0.2.0","changes":[…]} } ``` `sync_refs` reports the `[release.sync_refs]` stage (pack/doc version-ref rewrites folded into the bump commit — see [config](/reference/config#release-sync_refs)): `status` is `disabled` (no rules), `skipped` (+`reason`, e.g. mixed-version plan), `dry-run`, or `applied`; `changes[]` lists per-rule file/replacement counts and `changed_files` the touched paths. Dry-run results carry the same shape with `status:"dry-run"`. The `"sync-refs"` `steps_run` entry appears only when rules are configured. Failure shapes: * Plan/build error → op-level `{"ok":false,"error":"…"}`. * Mutation failure → `ok:false` result with `rolled_back` per-step report (remote tag deletes, branch reset, local cleanup). * Publish failure with nothing published → rollback, same shape. * Publish failure after a success → `ok:false`, `rolled_back: {"attempted":false,"reason":"…manual cleanup…"}` — state left in place deliberately. `steps_run` is the mutation-phase ledger; `publish` reports carry per-target `ok`, `disabled`, and target-specific fields (e.g. gh release URL, crates.io warnings). ## Common params | param | type | default | notes | | --- | --- | --- | --- | | `dir` | string | `"."` | repo root being released | | `profile` | string | — | profile name; precedence: param > `$TARSI_PROFILE` > config `profile` | | `range` | string | per-unit tag range | `"a..b"` rev range applied to **every** unit | | `dry_run` | bool | `true` | `release` only — `false` is the mutation opt-in | ## One-shot mapping `hypha-serve-cli` translates argv to params: ```bash tarsi-serve release --dir . --set profile=9aia-release --yes # ≡ {"op":"release","params":{"dir":".","profile":"9aia-release","dry_run":false}} ``` `--set k=v` values are strings; `--yes`/`--dry-run` set `dry_run`. --- --- url: /tarsi/reference/config.md --- # tarsi.toml schema The config document is `tarsi_core::Config` — TOML or YAML (`tarsi.yaml`/`tarsi.yml` preferred on discovery ties). Pure serde types in `crates/tarsi-core/src/config.rs`; loading/layering in `tarsi-config`. Secret **names** appear (`token_env`); values never do. ## Top level | key | type | required | meaning | | --- | --- | --- | --- | | `profile` | `string` | optional | Named release profile to layer *under* this config — a `type: tarsi` tamias pack or a dir under `~/.config/tarsi/profiles/`. Resolved by `tarsi-config` (profile dir becomes a config layer between the repo file and the user file); ignored by planning itself. | | `release` | `ReleaseConfig` | optional | — | | `publish` | `PublishConfig` | optional | — | ## `[release]` | key | type | required | meaning | | --- | --- | --- | --- | | `units` | `UnitsSpec` | optional | How release units resolve. Default: cargo workspace at root. | | `tag_format` | `string` | optional | Default tag template for units that don't override it. | | `changelog_path` | `string` | optional | Changelog file spliced per unit — resolved relative to each unit's path (`crates/foo` + `CHANGES.md` → `crates/foo/CHANGES.md`). | | `styleguide` | `string` | optional | keep-a-changelog | conventional-commit-grouped | … **Deprecated (P-030)** — superseded by \[`ReleaseConfig::strategy`]'s `changelog` section table. Still parsed for backward compat; has no effect on planning (it never did — the field was always descriptive). | | `strategy` | `StrategyRef` | optional | Release strategy (P-030): a builtin name (`"conventional"`, `"semantic-release-angular"`) or an inline rules table (`[release.strategy.bump]` / `[release.strategy.changelog]`). Absent = `conventional`, the pre-strategy behavior. Resolved inside `tarsi-serve`'s plan path so every op inherits it. | | `default_bump` | `Bump` | optional | Repo-wide default bump when inference finds nothing — honored as the strategy's `fallback` (P-030 wired the previously-dead field; an explicit `strategy.bump.fallback` wins). | | `diff_exclude` | `list` | optional | Path globs excluded from commit→unit attribution (e.g. `["docs/**", "*.md"]`). Wired in P-030: matching paths are stripped from each commit before attribution; a commit left with no paths is dropped entirely. | | `unit_overrides` | `BTreeMap` | optional | Per-unit overrides keyed by unit name. | | `sync_refs` | `SyncRefsConfig` | optional | Pack-ref/doc version sync — rewrite stale `name@old` / manifest `version:` refs in repo files *before* the release commit lands, so the tagged tree is self-consistent (T-039; replaces the per-repo `scripts/release.sh` pre-step). Empty `rules` = disabled — repos opt in. | ### `[release] strategy` The release *policy* as data (P-030): bump inference and changelog sectioning. Either a builtin name or an inline table — absent means `conventional`, the pre-strategy behavior. ```toml strategy = "conventional" # builtin name, OR inline: [release.strategy.bump] fallback = "patch" # bump when no rule matches [[release.strategy.bump.rules]] type = "feat" # raw conventional type token; "*"/absent = any scope = "core-*" # optional: exact or trailing-* glob breaking = true # optional: pin the !/BREAKING CHANGE flag not_type = ["fix"] # optional: type tokens that veto the match bump = "minor" # major|minor|patch|none [release.strategy.changelog] [[release.strategy.changelog.sections]] key = "added" # stable section id heading = "Added" # rendered as `### Added` [[release.strategy.changelog.sections.rules]] type = "feat" # same matcher fields, no `bump` ``` Semantics: * **Bump rules are max-match** — a commit contributes the highest `bump` across its matching rules; a unit folds max across its commits (semantic-release commit-analyzer's "highest release type wins" — rule order can't be gamed). `fallback` applies when inference finds nothing; `release.default_bump` fills it when the strategy doesn't set one. * **Changelog sections are first-match** — a commit lands in the first section (table order) with a matching rule; table order is also render order. Commits matching nothing are dropped. * Matchers run on the commit's **raw type token** — `deps`, `i18n`, and other non-`CommitKind` types are nameable. * Each absent `strategy.*` sub-table defaults to the `conventional` rules, so `[release.strategy.bump]` alone keeps the conventional changelog. * Builtin names: `conventional` (default — byte-identical to the pre-P-030 hardcoded policy), `semantic-release-angular` (the commit-analyzer angular preset as data), and `keep-a-changelog` (the keepachangelog.com section layout — see below). * The resolved strategy echoes on `plan` results as `plan.strategy {name, resolved}` (`name` = the builtin name or `"custom"`). What can't be data stays code: changelog render formats beyond section/heading/order, non-semver versioning, non-conventional commit parsing, anything needing execution (P-030 boundary). #### `keep-a-changelog` Keep a Changelog (keepachangelog.com) is a *changelog layout*, not a bump policy — the builtin keeps `conventional`'s bump rules verbatim and swaps only the section table for the six canonical sections, in keepachangelog.com order: | section | commits | | --- | --- | | `### Added` | `feat` | | `### Changed` | `refactor`, plus breaking commits of types with no section of their own (`chore!`, `deps!`, unknown `!` types) | | `### Deprecated` | `deprecate`, `deprecation` | | `### Removed` | `revert`, `remove` | | `### Fixed` | `fix`, `perf` | | `### Security` | `security` | Breaking commits of section-owning types stay in their own section (`fix!`→Fixed, `security!`→Security, …) — Changed's catch-all vetoes them via `not_type`. Types outside the table (`chore`, `docs`, `test`, `deps`, `release`, …) still count for bump inference but are dropped from the changelog. KaC-named types (`deprecate`, `revert`, `remove`, `security`) are changelog-only here — they don't move the version unless `default_bump` fills the fallback; a repo that wants e.g. `revert`→patch takes the same table inline with one extra bump rule. ### `[release.unit_overrides.]` | key | type | required | meaning | | --- | --- | --- | --- | | `bump` | `Bump` | optional | Force this unit's bump (beats inference). | | `tag_format` | `string` | optional | Per-unit tag template. | | `publish` | `Vec` | optional | Restrict publish targets (`"crates-io"`, `"github-release"`). | | `skip` | `bool` | optional | Skip this unit entirely (e.g. a lib that versions with its parent). | ### `[release.sync_refs]` | key | type | required | meaning | | --- | --- | --- | --- | | `rules` | `Vec` | optional | Rewrite rules, applied in order. Empty = the stage is disabled entirely (no files touched, no step reported). | #### sync rule (`rules[]` entries) | key | type | required | meaning | | --- | --- | --- | --- | | `files` | `list` | optional | Repo-root-relative globs of files to rewrite (`"libraries/myco/tamias.yaml"`, `"README.md"`, `".agents/skills/myco/SKILL.md"`). Non-matching globs are skipped — a repo can carry rules for files it doesn't have. | | `find` | `string` | required | Regex matching the stale ref. Required. | | `replace` | `string` | required | Literal replacement text. Required — an empty string would silently delete refs, so serde rejects a missing key. | Rewrites stale version refs in repo files *inside* the `bump`/`release` pipeline — after manifests are bumped, before the release commit — so the tagged tree is self-consistent. This is the stage that replaced the per-repo `scripts/release.sh` plan+`sed` pre-step (T-039): pack `tamias.yaml` manifest versions and `name@ver` README/SKILL install examples. ```toml [release.sync_refs] rules = [ # pack manifest version line (line anchor needs (?m)) { files = ["libraries/myco/tamias.yaml"], find = "(?m)^version: \"{old}\"", replace = "version: \"{new}\"" }, # doc refs — global, like the old `sed s|name@old|name@new|g` { files = ["README.md", ".agents/skills/myco/SKILL.md"], find = "myco@{old}", replace = "myco@{new}" }, ] ``` `{old}`/`{new}` expand to the releasing units' shared `current_version`/`new_version`. Inside `find` they are regex-escaped (so `.` stays literal); inside `replace` they expand literally. Patterns are **not** auto-bounded — `app@{old}` matches the `app@1.2.3` prefix of `app@1.2.30`, exactly like the old `sed` pre-steps; add `\b` when a boundary is needed (`regex` has no look-around). Use `(?m)` for line anchors. Semantics: * **Single-version only** — sync needs one unambiguous `old → new` pair. A plan whose releasing units disagree on `new_version` (or `current_version`) reports `status:"skipped"` and the release proceeds unsynced — the shims' `len(vs)==1` guard. * **Idempotent** — rules match the *old* version; once refs say `new`, nothing matches and the stage reports zero changes. * **Dry-run** — `bump`/`release` with `dry_run:true` (the default) reports `status:"dry-run"` plus `changed_files` without writing. * Results surface as `sync_refs{status, reason?, old, new, changes[], changed_files?}` on `bump` and `release`; `steps_run` gains a `"sync-refs"` entry between `bump-manifests` and `commit-bump` when rules are configured. Synced files are staged into the release commit itself — no separate pre-commit. ## `[publish]` | key | type | required | meaning | | --- | --- | --- | --- | | `crates` | `CratesPublish` | optional | crates.io publish target. | | `ghreleases` | `GhReleasePublish` | optional | GitHub Releases publish target. | | `dry_run` | `bool` | optional | Schema-level dry-run flag; the serve op's `dry_run` param is what callers use. | ### `[publish.crates]` | key | type | required | meaning | | --- | --- | --- | --- | | `enabled` | `bool` | optional | crates.io publishing on/off. | | `retry_429` | `bool` | optional | Retry crates.io 429s with backoff (release.sh semantics). | | `max_attempts` | `int` | optional | Max publish attempts per unit. | | `token_env` | `string` | optional | Env var NAME consulted for the crates.io token when `token_ref` is unset or misses — cargo reads `CARGO_REGISTRY_TOKEN`, and a resolved value is injected into the publish child's environment under that name. The value never appears in config, manifests, or logs. | | `token_ref` | `string` | optional | Optional `cuora://<scope>/<name>` secret ref — resolved via cuora at publish time and takes precedence over `token_env`. The value never appears in config or logs. | ### `[publish.ghreleases]` | key | type | required | meaning | | --- | --- | --- | --- | | `enabled` | `bool` | optional | GitHub Releases on/off. | | `token_env` | `string` | optional | Env var NAME holding the GitHub token — resolved via environment/cuora at publish time; the value never appears in config, manifests, or logs. | | `repo` | `string` | optional | Repo override `owner/name`; default = git remote. | | `token_ref` | `string` | optional | Optional `cuora://<scope>/<name>` secret ref — resolved via cuora at publish time and takes precedence over `token_env`. The value never appears in config or logs. | | `assets` | `list` | optional | Repo-root-relative glob patterns for release assets — `{unit}` and `{version}` expand per releasing unit, e.g. `["dist/{unit}-{version}-*", "{unit}/checksums.txt"]`. A pattern with no glob magic must match an existing file; magic patterns matching nothing are skipped. Empty = notes-only releases. | `bump` values: `"major"` | `"minor"` | `"patch"` | `"none"`. `PublishTarget` values: `"crates-io"` | `"github-release"`. ## Layering With a profile resolved, config loads through `LayeredFileSource` — objects merge key-wise, later layers fill gaps: ``` repo tarsi.* > profile tarsi.* > ~/.config/tarsi/ > defaults ``` Without a profile, discovery is first-match: `$TARSI_CONFIG` → `./tarsi.*` → `~/.config/tarsi/`. A missing profile name is a hard error; a present-but-broken `tarsi.*` file always errors loudly. ## Example See `tarsi.toml` at the repo root (dogfooding config) and `libraries/9aia-release/tarsi.toml` (the org profile). ## Constraints * Secret **names** (`token_env`, `token_ref`) appear in config; values never do — `cuora://` refs resolve via cuora at publish time, env names resolve through the environment. * Unknown fields are not rejected at this layer — `deny_unknown_fields` is not set on the config structs; typos surface as ignored keys, so check `tarsi-serve` plan output when a key seems inert. --- --- url: /tarsi/reference/pack-layout.md --- # Pack layout tarsi ships to the org as two tamias packs under `libraries/`. ## `libraries/tarsi` — the command pack `type: files` — ships the `tarsi-serve` binary. There is no `tarsi` CLI and no `shim: cli` bin by design (PL-014 surface split: release-expertise libs + `tarsi-serve` only). ```yaml # tamias.yaml (abridged) name: tarsi version: "0.1.0" type: files description: >- Generic release tool — changelog → semver bump → tag → publish. bins: - name: tarsi-serve payload: tools/bin/x86_64-unknown-linux-gnu/tarsi-serve ``` Layout: ``` libraries/tarsi/ ├── tamias.yaml # the manifest above └── tools/bin// # gitignored — `cargo xtask pack` stages └── tarsi-serve # release builds here per host triple ``` ```bash cargo xtask pack # build payload tamias install ./libraries/tarsi # deploy tarsi-serve → PATH # or, once published: tamias install tarsi@ ``` Dev shortcut: `cargo xtask install` puts a release `tarsi-serve` in `~/.local/bin` without the pack flow. ## `libraries/9aia-release` — the org profile pack `type: tarsi` — the org's release conventions as a layered config profile (PL-014 D2). ``` libraries/9aia-release/ ├── tamias.yaml # name/version/type: tarsi/description ├── tarsi.toml # THE profile — a plain Config document └── drivers/bin// # gitignored — `cargo xtask pack` stages └── tamias-driver-tarsi # the content driver here ``` The `type: tarsi` contract: * payload root MUST carry `tarsi.{yaml,yml,toml}` — no `[profile]` table (`profile` is the consumer-side selector key) * `tamias.yaml`'s `description` is the profile's human label * optional extras (`styleguide.md`, commit maps) resolve relative to the profile dir Install self-provisions the driver — tamias registers bundled drivers before dispatching `install`: ```bash cargo xtask pack tamias install --allow-drivers ./libraries/9aia-release ``` The store commit is the placement: the profile resolves by name, versioned by label, the moment tamias commits it. See [Author a release profile pack](/how-to/author-release-profile). ## xtask verbs | command | does | | --- | --- | | `cargo xtask check` | fmt + clippy `-D warnings` | | `cargo xtask test` | whole suite (nextest if present) | | `cargo xtask pack` | release-build `tarsi-serve` → `libraries/tarsi/tools/bin//` **and** `tamias-driver-tarsi` → `libraries/9aia-release/drivers/bin//` | | `cargo xtask install` | release `tarsi-serve` → `~/.local/bin` (dev shortcut) | Both payload dirs are gitignored build artifacts — the manifests are the source of truth. --- --- url: /tarsi/reference/crates.md --- # Crates Rust workspace, ports-and-adapters — the same anatomy as tamias/bupha/peregrin. `tarsi-core` is pure domain (no I/O); `tarsi-serve` is the composition root and the only shipped binary. | crate | layer | purpose | |---|---|---| | `tarsi-core` | domain | Pure release-domain model — plans, units, semver bumps, commit classification, changelog. No I/O. | | `tarsi-publish` | port | Publish port — per-forge Publisher impls (crates.io, GitHub Releases, dry-run). | | `tarsi-config` | adapter | tarsi.toml/tarsi.yml loading — scarab-config file discovery over tarsi_core::Config, plus type:tarsi release-profile resolution. | | `tarsi-manifest` | adapter | Cargo manifest scanning — workspace members → tarsi_core::ReleaseUnitSpec, version reads/writes. | | `tarsi-publish-crates` | adapter | crates.io Publisher — dep-ordered cargo publish with 429 retry (release.sh semantics). | | `tarsi-publish-dryrun` | adapter | Dry-run Publisher — validates and reports every target without remote writes. | | `tarsi-publish-ghreleases` | adapter | GitHub Releases publisher — release create + notes + asset upload via ureq (blocking, bupha-github convention). | | `tarsi-serve` | engine | tarsi service surface — ndjson ops (plan/changelog/notes/check/schema + granular bump/tag/publish + release) over tarsi-core + lasius-vcs. | | `tarsi-driver` | driver | tamias-driver-tarsi — tamias content driver for type:tarsi release-profile packs | | `tarsi-testkit` | testkit | Conformance fixtures + golden corpus for tarsi ports/impls. | | `tarsi-xtask` | tooling | Repo chores: check / test / coverage / install / package / smoke / site | ## Key external deps * `lasius-vcs` + `lasius-vcs-git` — all git history/tag/push (P-019); `tarsi-core` sees only `Commit` values. * `scarab-config` + `scarab-config-file` — config discovery and layering (P-017); no `tarsi-config-*` format crates. * `hypha-serve-cli` — the shared one-shot argv→params shim. * `semver`, `toml_edit`, `serde`/`serde_json` — versions, manifest mutation, the wire. API docs: `bun run docs:api` renders `cargo doc` into `public/api/` (linked from the built site under `/tarsi/api/`). --- --- url: /tarsi/public/api/static.files/SourceSerif4-LICENSE-a2cfd9d5.md --- Copyright 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries. Copyright 2014 - 2023 Adobe (http://www.adobe.com/), with Reserved Font Name ‘Source’. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries. This Font Software is licensed under the SIL Open Font License, Version 1.1. This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL *** ## SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 PREAMBLE The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects, to support the font creation efforts of academic and linguistic communities, and to provide a free and open framework in which fonts may be shared and improved in partnership with others. The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed and/or sold with any software provided that any reserved names are not used by derivative works. The fonts and derivatives, however, cannot be released under any other type of license. The requirement for fonts to remain under this license does not apply to any document created using the fonts or their derivatives. DEFINITIONS "Font Software" refers to the set of files released by the Copyright Holder(s) under this license and clearly marked as such. This may include source files, build scripts and documentation. "Reserved Font Name" refers to any names specified as such after the copyright statement(s). "Original Version" refers to the collection of Font Software components as distributed by the Copyright Holder(s). "Modified Version" refers to any derivative made by adding to, deleting, or substituting -- in part or in whole -- any of the components of the Original Version, by changing formats or by porting the Font Software to a new environment. "Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the Font Software. PERMISSION & CONDITIONS Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use, study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software, subject to the following conditions: 1. Neither the Font Software nor any of its individual components, in Original or Modified Versions, may be sold by itself. 2. Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold with any software, provided that each copy contains the above copyright notice and this license. These can be included either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata fields within text or binary files as long as those fields can be easily viewed by the user. 3. No Modified Version of the Font Software may use the Reserved Font Name(s) unless explicit written permission is granted by the corresponding Copyright Holder. This restriction only applies to the primary font name as presented to the users. 4. The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software shall not be used to promote, endorse or advertise any Modified Version, except to acknowledge the contribution(s) of the Copyright Holder(s) and the Author(s) or with their explicit written permission. 5. The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license, and must not be distributed under any other license. The requirement for fonts to remain under this license does not apply to any document created using the Font Software. TERMINATION This license becomes null and void if any of the above conditions are not met. DISCLAIMER THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.