mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-10 03:51:29 -10:00
Aron PrinsandClaude Opus 4.7
02dbbf83a7
Scaffolds the data layer for the /sync-docs skill: - scripts/sync/anchor-map.json — declares which parent-repo paths each watcher tracks, where they route in our docs, and whether changes are auto-merge (mechanical, schema-bound) or PR tier (judgment calls). - scripts/sync/state.example.json — template for .sync-state.json. - .sync-state.json — per-branch sync state, seeded for an initial release-mode run from v2026.318.0. - docs/user-guides/screenshots/registry.json — screenshot dependency tracking so the skill can flag stale captures. The skill itself follows in the next commit. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
48 lines
2.1 KiB
Markdown
48 lines
2.1 KiB
Markdown
# scripts/sync — Doc-sync engine config
|
|
|
|
Configuration and state for the **`/sync-docs`** skill (see `.claude/skills/sync-docs/SKILL.md`).
|
|
|
|
This directory holds data, not code. The skill itself is the orchestrator; it reads these files to decide what to watch, where to route changes, and where it last left off.
|
|
|
|
## Files
|
|
|
|
| File | Purpose | Committed? |
|
|
|---|---|---|
|
|
| `anchor-map.json` | Maps parent-repo paths → docs-repo paths, with detection rules and tier (auto-merge vs PR) | Yes |
|
|
| `state.example.json` | Template for `.sync-state.json` | Yes |
|
|
| `../../.sync-state.json` | Current sync state for the branch (last synced parent ref) | Yes, per-branch |
|
|
|
|
## Branch model
|
|
|
|
- **`main` (docs)** tracks the latest **released** paperclip tag (e.g. `v2026.512.0`). Deploys to docs.paperclip.ing.
|
|
- **`nightly` (docs)** tracks parent's `main` HEAD. Deploys to the Cloudflare Pages branch preview.
|
|
|
|
`.sync-state.json` therefore has a different value on each branch:
|
|
|
|
```jsonc
|
|
// on main
|
|
{ "mode": "release", "synced_to": "v2026.512.0", "synced_sha": "abc123…" }
|
|
|
|
// on nightly
|
|
{ "mode": "nightly", "synced_to": "main", "synced_sha": "def456…" }
|
|
```
|
|
|
|
## Anchor map
|
|
|
|
Each watcher entry declares:
|
|
|
|
- `parent_paths` — globs in github.com/paperclipai/paperclip to watch.
|
|
- `docs_paths` — globs in this repo where corresponding doc edits live.
|
|
- `tier` — `auto-merge` (mechanical, schema-bound), `pr` (judgment calls), or `context-only` (informs other watchers but never produces edits directly).
|
|
- `detect` — short prose telling the skill *how* to recognise a doc-relevant change in those files (e.g. "new `program.command()` calls", "new top-level dir").
|
|
|
|
The skill reads this file at the start of every run. Edit it when you add new doc sections or new product surfaces.
|
|
|
|
## Skip patterns
|
|
|
|
`skip_patterns` are regexes matched against parent commit messages. Anything matching is ignored entirely — this is the first line of defence against revert/wip/codex churn.
|
|
|
|
## Quarantine
|
|
|
|
`quarantine_hours` (default 24) tells nightly mode to ignore commits younger than N hours. Reverts and fix-ups tend to land in this window and cancel out before we draft anything.
|