---
name: sync-team-profiles
description: >
  Fetch (or refresh) registered team-profile sources — git clone on
  first run, shallow git fetch + reset on subsequent runs — and
  register discovered profiles under a namespace.
  TRIGGER when the user says "sync team profiles", "pull the latest
  team profiles", "refresh team profiles", "update team profiles",
  "sync from <team-name> profile source", "fetch profiles from the
  team repo", "/nyann:sync-team-profiles".
  Do NOT trigger on "add a new team profile source" (that's
  `add-team-source` — registers without pulling). Do NOT trigger on
  "sync my branch" (that's the `sync` skill — feature-branch
  rebase/merge). Do NOT trigger on "install a profile" from a URL
  when no source is registered yet — walk the user through
  `add-team-source` first.
---

# sync-team-profiles

Wraps `bin/sync-team-profiles.sh`.
On first run it shallow-clones each registered team-profile source
(`git clone --depth=1`); on subsequent runs it does a shallow fetch
(`git fetch --depth=1`) and `git reset --hard FETCH_HEAD` to advance
to the latest commit. Every profile under the cache is then validated
against `profiles/_schema.json`, and valid profiles are registered
under `<source-name>/<profile-name>`.

## 1. Pre-flight

- Config at `~/.claude/nyann/config.json` must have at least one
  entry in `team_profile_sources[]`. If empty, route to
  `add-team-source` first.
- Uses the sync interval from each source. When the user says
  "force refresh" / "ignore the interval" / "pull now", pass
  `--force`.
- When the user names a specific source ("sync just the platform-
  team profiles"), pass `--name <source>` so unrelated sources
  don't get pulled.

## 2. Invoke

```
bin/sync-team-profiles.sh \
  [--user-root <dir>] \
  [--force] \
  [--name <source>]
```

Network operation. Expect up to a few seconds per source. The
backend is resilient — a failing source logs the error and moves
on to the next.

## 3. Interpret the JSON summary

Top-level shape is four arrays (see `schemas/team-sync-result.schema.json`):

- `synced[]` — sources that pulled this run. Each entry: `{name, synced_at}`.
- `skipped[]` — sources within their interval window. Each entry:
  `{name, reason: "within-interval", next_due}`. Tell the user the
  next-due timestamp; they can re-run with `--force` if they need
  to pull immediately.
- `registered[]` — every profile that passed schema validation.
  Each entry: `{source, name, namespaced, path}`. The `namespaced`
  field is what to use with `bootstrap-project --profile <namespaced>`.
- `invalid[]` — anything that didn't make it through (fetch
  failure, clone failure, hand-edited config with a bad ref/url,
  TOCTOU on the cache dir, profile that fails schema validation).
  Each entry: `{name|source, kind, error}` where `kind` is one of
  `invalid-name`, `invalid-ref`, `invalid-url`, `fetch-failed`,
  `clone-failed`, `toctou`, `invalid-schema`. Show these but don't
  treat any single one as fatal — the script logs and moves on to
  the next source.

## 4. After sync

- Tell the user how many profiles are newly available.
- Suggest `inspect-profile <source>/<name>` to see what a specific
  team profile does.
- Suggest `bootstrap-project --profile <source>/<name>` to apply
  one to a repo.

## 5. When a source errors

- `git clone` / `git fetch` failures are usually auth or network
  issues and surface in `invalid[]` with `kind: clone-failed` or
  `fetch-failed`. The error string passes through `nyann::redact_url`
  before reaching the JSON, so any embedded `https://<token>@host`
  credentials are scrubbed — safe to relay verbatim. Don't try to
  auth-fix on the user's behalf.
- Corrupted cache (`<user-root>/cache/<source>/` contains partial
  data) — safe to delete the cache dir and re-run. Confirm before
  deleting; it's a file-system mutation.

## When to hand off

- "Add a new source" → `add-team-source`.
- "My team profile collides with a starter profile" — by design,
  user + team profiles can shadow starters. Clarify which version
  will win (user > team > starter) and let the user decide if the
  shadow is intentional.
- "Drift detection: is my cached team profile out of sync with the
  remote?" → that's `check-team-drift` (separate backend; not in
  this skill's scope).