Add file exclusion via josh stored filters (v1.2.0)

New `exclude` config field per target generates .josh-filters/<name>.josh
files with josh :exclude clauses. Josh-proxy applies exclusions at the
transport layer — excluded files never appear in the subrepo.

Preflight checks that generated filter files are committed.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/guide.md

@@ -91,6 +91,9 @@ targets:
     branches:
       main: main                             # mono_branch: subrepo_branch
     forward_only: []
+    exclude:                                 # files excluded from subrepo (optional)
+      - ".monorepo/"                         # monorepo-only config dir
+      - "**/internal/"                       # internal dirs at any depth
 
   - name: "auth"
     subfolder: "services/auth"
@@ -515,6 +518,66 @@ Bot commits include a git trailer like `Josh-Sync-Origin: forward/main/2024-02-1
 
 Sync state is stored as JSON files on an orphan branch (`josh-sync-state`), one file per target/branch. This tracks the last-synced commit SHAs and timestamps to avoid re-syncing the same changes.
 
+## Excluding Files from Sync
+
+Some files in the monorepo subfolder may not belong in the subrepo (e.g., monorepo-specific CI configs, internal tooling). The `exclude` config field removes these at the josh-proxy layer — excluded files never appear in the subrepo.
+
+### Configuration
+
+Add an `exclude` list to any target:
+
+```yaml
+targets:
+  - name: "billing"
+    subfolder: "services/billing"
+    subrepo_url: "git@host:org/billing.git"
+    exclude:
+      - ".monorepo/"          # directory at subfolder root
+      - "**/internal/"        # directory at any depth
+      - "*.secret"            # files by extension
+    branches:
+      main: main
+```
+
+### How it works
+
+When `exclude` is present, josh-sync generates a `.josh-filters/<target>.josh` file containing a [josh stored filter](https://josh-project.github.io/josh/reference/filters.html) with `:exclude` clauses:
+
+```
+:/services/billing:exclude[
+  ::.monorepo/
+  ::**/internal/
+  ::*.secret
+]
+```
+
+Josh-proxy reads this file from the monorepo and applies the filter at the transport layer. This means:
+- **Forward sync**: the filtered clone already excludes the files
+- **Reverse sync**: pushes through josh also respect the exclusion
+- **Reset**: the subrepo history never contains excluded files
+- **Tree comparison**: `skip` detection works correctly (excluded files are not in the diff)
+
+### Pattern syntax
+
+Josh uses `::` patterns inside `:exclude[...]`:
+
+| Pattern | Matches |
+|---------|---------|
+| `dir/` | Directory at subfolder root |
+| `file` | File at subfolder root |
+| `**/dir/` | Directory at any depth |
+| `**/file` | File at any depth |
+| `*.ext` | Glob pattern (single `*` only) |
+
+### Setup
+
+1. Add `exclude` to the target in `.josh-sync.yml`
+2. Run `josh-sync preflight` — this generates `.josh-filters/<target>.josh`
+3. Commit the generated file: `git add .josh-filters/ && git commit`
+4. Forward sync will now exclude the specified files
+
+If you change the `exclude` list, re-run `preflight` and commit the updated `.josh-filters/` file.
+
 ## Adding a New Target
 
 To add a new subrepo after initial setup: