docs: update sections

Author: pivoshenko

docs/authentication.md

@@ -52,9 +52,9 @@ Kasetto identifies the git host from the URL hostname:
 
 Works for `github.com` and GitHub Enterprise Server alike.
 
-```console
-$ export GITHUB_TOKEN=ghp_...
-$ kst sync --config kasetto.yaml
+```bash
+export GITHUB_TOKEN=ghp_...
+kst sync --config kasetto.yaml
 ```
 
 ### GitLab
@@ -66,9 +66,9 @@ $ kst sync --config kasetto.yaml
 
 Works for `gitlab.com` and any self-hosted instance whose hostname starts with `gitlab.`.
 
-```console
-$ export GITLAB_TOKEN=glpat-...
-$ kst sync --config kasetto.yaml
+```bash
+export GITLAB_TOKEN=glpat-...
+kst sync --config kasetto.yaml
 ```
 
 ### Bitbucket Cloud
@@ -105,9 +105,9 @@ All three are checked in order — the first one found is used for any Gitea-fam
 
 Authentication also applies when you fetch a config via `--config <url>`. The token is chosen based on the URL hostname, using the same detection rules above.
 
-```console
-$ export GITHUB_TOKEN=ghp_...
-$ kst sync --config https://github.com/org/private-repo/raw/main/kasetto.yaml
+```bash
+export GITHUB_TOKEN=ghp_...
+kst sync --config https://github.com/org/private-repo/raw/main/kasetto.yaml
 ```
 
 If the URL points to a private resource and no matching token is set, Kasetto reports an HTTP error with a hint about which variable to set.

docs/ci.md

@@ -0,0 +1,73 @@
+# CI & Automation
+
+**When you need this:** You want to validate `kasetto.yaml` in CI, keep team environments reproducible, or integrate Kasetto into scripts.
+
+**What you'll learn:**
+
+- Recommended flags (`--dry-run`, `--json`, `--plain`, `--quiet`)
+- Exit-code expectations
+- A GitHub Actions example
+
+## Recommended Commands
+
+### Validate Without Writing
+
+Use `--dry-run` to check that sources resolve and that the plan matches expectations without touching disk:
+
+```bash
+kst sync --dry-run
+```
+
+### JSON Output for CI Logs
+
+Use `--json` for structured logs:
+
+```bash
+kst sync --dry-run --json
+```
+
+### Avoid TUIs in Non-Interactive Environments
+
+Kasetto will avoid interactive UIs when it detects non-interactive output, but you can force it:
+
+- Set `NO_TUI=1`
+- Or use `--plain` / `--quiet` as needed
+
+```bash
+NO_TUI=1 kst sync --dry-run --plain
+```
+
+## Exit Codes
+
+Kasetto is designed to keep going when individual skills are missing/broken in a source, but failures that prevent reading sources/configs are treated as errors.
+
+If you're depending on strict enforcement in CI, pair `--dry-run` with `--json` and enforce policy in the CI step based on the report.
+
+## GitHub Actions Example
+
+This validates a repo's `kasetto.yaml` (project scope) without writing changes:
+
+```yaml
+name: kasetto
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install kasetto
+        run: curl -fsSL https://raw.githubusercontent.com/pivoshenko/kasetto/main/scripts/install.sh | sh
+
+      - name: Validate kasetto.yaml
+        env:
+          NO_TUI: "1"
+          # Add tokens if you pull from private sources:
+          # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: kst sync --project --dry-run --json
+```

docs/commands.md

@@ -4,8 +4,8 @@
 
 Generates a starter `kasetto.yaml` in the current directory — a good jumping-off point before you edit by hand.
 
-```console
-$ kst init [OPTIONS]
+```bash
+kst init [OPTIONS]
 ```
 
 ### Options
@@ -18,8 +18,8 @@ $ kst init [OPTIONS]
 
 Reads your config, fetches any remote skills, and brings your local install up to date.
 
-```console
-$ kst sync [OPTIONS]
+```bash
+kst sync [OPTIONS]
 ```
 
 ### Options
@@ -45,8 +45,8 @@ Missing skills are reported as broken but won't stop the rest of the run. The ex
 
 Shows everything Kasetto has installed (skills and MCP servers from the lock file).
 
-```console
-$ kst list [OPTIONS]
+```bash
+kst list [OPTIONS]
 ```
 
 ### Options
@@ -72,8 +72,8 @@ In a terminal (and without `--plain`), this opens an interactive browser — **S
 
 Prints a local health check: your version, lock file location, install paths, last sync time, and any skills that failed.
 
-```console
-$ kst doctor [OPTIONS]
+```bash
+kst doctor [OPTIONS]
 ```
 
 ### Options
@@ -90,8 +90,8 @@ $ kst doctor [OPTIONS]
 
 Removes everything Kasetto installed for the given scope — skills, MCP configs, and lock file entries.
 
-```console
-$ kst clean [OPTIONS]
+```bash
+kst clean [OPTIONS]
 ```
 
 ### Options
@@ -113,8 +113,8 @@ Manage Kasetto itself — update to a new version or remove it completely.
 
 Fetches the latest release from GitHub and swaps out the binary in-place.
 
-```console
-$ kst self update [OPTIONS]
+```bash
+kst self update [OPTIONS]
 ```
 
 #### Options
@@ -132,8 +132,8 @@ $ kst self update [OPTIONS]
 
 A full teardown: removes installed skills and MCP configs, clears Kasetto's data directories, and deletes the binary.
 
-```console
-$ kst self uninstall [OPTIONS]
+```bash
+kst self uninstall [OPTIONS]
 ```
 
 #### Options
@@ -146,8 +146,8 @@ $ kst self uninstall [OPTIONS]
 
 Generates completion scripts for your shell.
 
-```console
-$ kst completions <SHELL>
+```bash
+kst completions <SHELL>
 ```
 
 Supported shells: `bash`, `zsh`, `fish`, `powershell`.

docs/configuration.md

@@ -99,8 +99,8 @@ for Cursor). See [how sync works](./how-sync-works.md) for merge behavior detail
 
 Kasetto can fetch configs from any HTTPS URL:
 
-```console
-$ kst sync --config https://example.com/team-skills.yaml
+```bash
+kst sync --config https://example.com/team-skills.yaml
 ```
 
 Great for sharing a single config across a team without checking it into every repository.
@@ -132,7 +132,7 @@ If you set both, `destination` wins. Use `agent` for convenience with [supported
 
     Use `destination` when targeting an agent that isn't in the supported list.
 
-## Scope: Global vs Project
+## Scope: Global Vs Project
 
 By default, skills are installed globally into the agent's home-directory path. Add `scope: project` to your config, or pass `--project` on the command line, to install into the current project directory instead.
 

docs/cookbook.md

@@ -0,0 +1,91 @@
+# Cookbook
+
+**When you need this:** You want copy-paste setups for common real workflows (teams, monorepos, multiple agents, pinned rollouts).
+
+**What you'll learn:**
+
+- Patterns that work well in practice
+- How to pin and roll out changes safely
+
+## Team Bootstrap From A URL Config
+
+Host a shared `kasetto.yaml` somewhere reachable over HTTPS (public or private), then have each developer run:
+
+```bash
+kst sync --config https://example.com/team/kasetto.yaml
+```
+
+For private configs hosted on git providers, set the matching token env var (see [Authentication](./authentication.md)).
+
+## Monorepo: Project Scope Per Workspace
+
+Keep one `kasetto.yaml` per workspace folder and make it project-scoped:
+
+```yaml
+scope: project
+agent: cursor
+
+skills:
+  - source: https://github.com/acme/monorepo-skills
+    skills:
+      - code-reviewer
+      - doc-coauthoring
+```
+
+Then run sync from each workspace directory:
+
+```bash
+kst sync
+```
+
+Each workspace gets its own `./kasetto.lock`.
+
+## Multiple Agents From One Config
+
+Install the same skills (and MCP servers) into multiple agents:
+
+```yaml
+agent:
+  - claude-code
+  - cursor
+  - codex
+
+skills:
+  - source: https://github.com/acme/skills
+    skills: "*"
+
+mcps:
+  - source: https://github.com/acme/mcp-packs
+```
+
+## MCP Packs: Pinning And Rollouts
+
+Pin an MCP pack source to a git tag or commit SHA:
+
+```yaml
+agent: claude-code
+
+skills:
+  - source: https://github.com/acme/skills
+    skills: "*"
+
+mcps:
+  - source: https://github.com/acme/mcp-packs
+    ref: v2.4.1
+```
+
+Roll forward by bumping `ref`, then use `--dry-run` to preview:
+
+```bash
+kst sync --dry-run
+```
+
+## Explicit MCP Pack Path (`mcps.path`)
+
+If a repo contains multiple MCP config files or doesn't match the default discovery layout, point directly at one:
+
+```yaml
+mcps:
+  - source: https://github.com/acme/monorepo
+    path: mcps/servers/pack.json
+```

docs/faq.md

@@ -0,0 +1,54 @@
+# FAQ
+
+**When you need this:** You have a quick "what happens if…" question about syncing skills or MCP servers.
+
+## Will Kasetto Overwrite My MCP Entries?
+
+No. MCP merges are **additive** and existing server entries are **never overwritten**. See [How Sync Works](./how-sync-works.md#mcp-servers-discovery-and-additive-merge).
+
+## What Happens When Two Sources Define The Same MCP Server Name?
+
+**First write wins** based on config order. Later sources with the same server name are skipped. See [How Sync Works](./how-sync-works.md#edge-cases).
+
+## Where Is The Lock File?
+
+- **Global scope**: `$XDG_DATA_HOME/kasetto/kasetto.lock` (default: `~/.local/share/kasetto/kasetto.lock`)
+- **Project scope**: `./kasetto.lock`
+
+See [How Sync Works](./how-sync-works.md#lock-file).
+
+## How Do I Uninstall Safely?
+
+- To remove tracked installs for a scope: `kst clean`
+- To remove everything including the binary: `kst self uninstall`
+
+See `kst clean` and `kst self uninstall` in [Commands](./commands.md).
+
+## Can I Use Multiple Agents?
+
+Yes. Set `agent` to a list. See [Configuration](./configuration.md#multiple-agents).
+
+## Does Kasetto Run Code From Skills?
+
+No. Skills are copied as directories. Execution is up to the agent you load them into.
+
+## Can I Pin Sources To A Known-Good Version?
+
+Yes. Use `ref:` with a tag or commit SHA. See [Cookbook](./cookbook.md#mcp-packs-pinning-and-rollouts).
+
+## What Does `--dry-run` Do?
+
+It prints what would change without writing any files. Useful in CI. See [CI & automation](./ci.md).
+
+## Why Didn't My MCP Servers Show Up?
+
+Most common causes:
+
+- The target agent settings file is malformed JSON/TOML
+- The MCP file doesn't contain a top-level `mcpServers` object
+
+See [How Sync Works](./how-sync-works.md#edge-cases) (corrupted settings file behavior).
+
+## How Do Remote Configs (`--config https://...`) Authenticate?
+
+Kasetto selects tokens by the URL hostname using the same rules as skill/MCP sources. See [Authentication](./authentication.md#remote-configs).