"#"

docs/config-reference.md

@@ -0,0 +1,79 @@
+# Configuration Reference
+
+Full reference for `.josh-sync.yml` fields and environment variables.
+
+## `.josh-sync.yml` Structure
+
+```yaml
+josh:       # josh-proxy settings (required)
+targets:    # sync targets (required, at least 1)
+bot:        # bot identity for sync commits (required)
+```
+
+## `josh` Section
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `proxy_url` | string | Yes | Josh-proxy URL, no trailing slash. Must start with `http://` or `https://`. |
+| `monorepo_path` | string | Yes | Repository path as josh-proxy sees it (e.g., `org/monorepo`). |
+
+## `targets[]` Section
+
+Each target maps a monorepo subfolder to an external subrepo.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | — | Unique target identifier. Used in CLI commands and state tracking. |
+| `subfolder` | string | Yes | — | Monorepo subfolder path (e.g., `services/billing`). |
+| `josh_filter` | string | No | `:/<subfolder>` | Josh filter expression. Auto-derived from `subfolder` if omitted. Must start with `:`. |
+| `subrepo_url` | string | Yes | — | External subrepo Git URL. Supports HTTPS (`https://...`), SSH (`git@host:path`), and `ssh://` formats. |
+| `subrepo_auth` | string | No | `"https"` | Auth method: `"https"` or `"ssh"`. |
+| `subrepo_token_var` | string | No | `"SUBREPO_TOKEN"` | Name of the env var holding the HTTPS token for this target. |
+| `subrepo_ssh_key_var` | string | No | `"SUBREPO_SSH_KEY"` | Name of the env var holding the SSH private key for this target. |
+| `branches` | object | Yes | — | Branch mapping: `mono_branch: subrepo_branch`. Each key-value pair syncs those branches bidirectionally. |
+| `forward_only` | string[] | No | `[]` | Branches that only sync mono → subrepo, never reverse. |
+
+## `bot` Section
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Git author name for sync commits. |
+| `email` | string | Yes | Git author email for sync commits. |
+| `trailer` | string | Yes | Git trailer key for loop prevention (e.g., `Josh-Sync-Origin`). |
+
+## Environment Variables
+
+### Credentials
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `SYNC_BOT_USER` | Bot's Git username | — |
+| `SYNC_BOT_TOKEN` | API token for monorepo access and josh-proxy HTTPS auth | — |
+| `SUBREPO_TOKEN` | HTTPS token for subrepo access | Falls back to `SYNC_BOT_TOKEN` |
+| `SUBREPO_SSH_KEY` | SSH private key content (not a file path) for subrepo access | — |
+
+### Per-target credential overrides
+
+Set `subrepo_token_var` or `subrepo_ssh_key_var` in a target's config to read credentials from a different env var:
+
+```yaml
+targets:
+  - name: "auth"
+    subrepo_token_var: "AUTH_REPO_TOKEN"    # reads from $AUTH_REPO_TOKEN
+    subrepo_ssh_key_var: "AUTH_SSH_KEY"      # reads from $AUTH_SSH_KEY
+```
+
+**Resolution order:** per-target env var → default env var (`SUBREPO_TOKEN` / `SUBREPO_SSH_KEY`) → `SYNC_BOT_TOKEN` fallback.
+
+### Runtime
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `JOSH_SYNC_TARGET` | Restrict sync to a single target | All targets |
+| `JOSH_SYNC_STATE_BRANCH` | Name of the orphan branch for state storage | `josh-sync-state` |
+| `JOSH_SYNC_DEBUG` | Enable verbose logging (`1` to enable) | `0` |
+| `MONOREPO_API` | Override monorepo API URL | Auto-derived from first target's host |
+
+## JSON Schema
+
+The config file can be validated against the JSON Schema at [`schema/config-schema.json`](../schema/config-schema.json).