Add sync protocol for portable context management

- ai-sync-protocol.md: Session start and post-change sync rules
- _sync section in schema for auto-sync configuration
- Updated client skill template with Forgejo fetch patterns
- Client projects now self-sufficient via central repo fetch

Version 1.1.0

Made-with: Cursor

.cursor/rules/ai-sync-protocol.md

@@ -0,0 +1,204 @@
+# AI Context Sync Protocol
+
+This rule defines how context is synchronized between the central ai-ops-templates repository and individual client projects.
+
+---
+
+## Architecture Overview
+
+```
+Abundance Project (Central)
+       │
+       ▼ (push after changes)
+   Forgejo Repo ──────────────────┐
+       │                          │
+       ▼ (pull at session start)  │
+   Client Project A               │
+   Client Project B ◄─────────────┘
+   Client Project C
+```
+
+- **Central Hub**: Abundance project manages all skills, rules, and templates
+- **Single Source of Truth**: `https://git.abundancepartners.app/matt/ai-ops-templates`
+- **Client Projects**: Self-sufficient, fetch everything from Forgejo
+
+---
+
+## MANDATORY: Session Start Protocol
+
+When starting work in ANY project, follow this sequence:
+
+### Step 1: Check for .ai-context.json
+```json
+// Read this file first if it exists
+{
+  "_sync": {
+    "templates_repo": "https://git.abundancepartners.app/matt/ai-ops-templates",
+    "last_check": "2026-03-06T16:00:00Z",
+    "auto_sync": true
+  }
+}
+```
+
+### Step 2: Determine if Sync Needed
+Check if `last_check` is:
+- **Null or missing**: MUST sync now
+- **> 24 hours old**: SHOULD sync now
+- **< 24 hours old**: Optional (use cached context)
+
+### Step 3: Fetch Fresh Context from Forgejo
+Use these raw URLs to fetch context:
+```
+# Brand preset
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{client}.json
+
+# Templates
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/templates/{template}.json
+
+# Rules
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/rules/{rule}.md
+
+# Snippets
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/{snippet}.tsx
+```
+
+### Step 4: Update last_check Timestamp
+After fetching, update `.ai-context.json`:
+```json
+{
+  "_sync": {
+    "last_check": "<current ISO timestamp>"
+  }
+}
+```
+
+---
+
+## MANDATORY: Post-Change Sync Protocol
+
+After making changes that affect shared context:
+
+### Step 1: Identify Change Type
+| Change Type | Action Required |
+|-------------|-----------------|
+| Client-specific code | No sync needed |
+| New reusable pattern | Sync to central |
+| Brand/styling change | Update preset, sync |
+| Bug fix with general solution | Add to common-fixes, sync |
+| New component template | Add to snippets, sync |
+
+### Step 2: Update Central Repository
+If in the Abundance project:
+1. Update the relevant file in `ai-ops-templates/`
+2. Update `context/last-sync.json` timestamps
+3. Add entry to `context/CHANGELOG.md`
+4. Git commit and push to Forgejo
+
+If in a client project:
+1. Identify the change that should be shared
+2. Push the change to Forgejo ai-ops-templates repo
+3. Update `context/last-sync.json`
+
+### Step 3: Verify Sync
+Confirm the change is visible at:
+```
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/{path}
+```
+
+---
+
+## Context File Locations
+
+### In Abundance Project (Central)
+```
+ai-ops-templates/
+├── presets/{client}.json       # Brand colors, fonts, config
+├── templates/{name}.json       # Schema.org templates
+├── rules/{name}.md             # Development rules
+├── snippets/{name}.tsx         # Reusable code
+├── schemas/{name}.schema.json  # JSON schemas
+└── context/
+    ├── CHANGELOG.md            # Change history
+    └── last-sync.json          # Timestamps
+```
+
+### In Client Projects
+```
+.ai-context.json                # Pointer to Forgejo + client config
+.cursor/skills/{client}/SKILL.md  # Client-specific skill
+```
+
+---
+
+## Fetching Context Examples
+
+### Fetch a Brand Preset
+```javascript
+// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/slc-bride.json
+{
+  "brand": {
+    "colors": { "primary": "#ec4899", ... },
+    "fonts": { "heading": "Playfair Display", ... }
+  }
+}
+```
+
+### Fetch a Snippet
+```typescript
+// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/vendor-card.tsx
+export function VendorCard({ vendor }: VendorCardProps) { ... }
+```
+
+### Fetch a Rule
+```markdown
+// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/rules/seo-rules.md
+# SEO Rules
+...
+```
+
+---
+
+## Error Handling
+
+### Cannot Reach Forgejo
+1. Use cached context if `last_check < 24 hours`
+2. Proceed with work, note that sync is pending
+3. Retry sync at end of session
+
+### Context File Not Found
+1. Check if file exists in central repo
+2. If new client, use `presets/default.json` as base
+3. Create client-specific preset in central repo
+
+### Merge Conflicts
+1. Prefer central repo version for templates/rules
+2. Keep client-specific overrides in local `.ai-context.json`
+3. Document conflict resolution in CHANGELOG
+
+---
+
+## Quick Reference
+
+| Action | Command/URL |
+|--------|-------------|
+| Check if sync needed | Read `.ai-context.json` → check `_sync.last_check` |
+| Fetch preset | `GET .../raw/main/presets/{client}.json` |
+| Fetch template | `GET .../raw/main/templates/{name}.json` |
+| Fetch snippet | `GET .../raw/main/snippets/{name}.tsx` |
+| Push changes | `git add . && git commit -m "..." && git push` |
+| Verify sync | Check raw URL in browser |
+
+---
+
+## Self-Healing Protocol
+
+If context seems stale or incorrect:
+
+1. **Force refresh**: Set `_sync.last_check` to null, restart session
+2. **Verify source**: Check Forgejo repo directly in browser
+3. **Rebuild**: Delete local context, fetch fresh from Forgejo
+4. **Report**: Add issue to central repo if problem persists
+
+---
+
+*This rule is managed centrally in the Abundance project and synced to client projects via the ai-ops-templates repository.*

context/CHANGELOG.md

@@ -24,6 +24,24 @@ This file tracks all changes to the ai-ops-templates repository. Updates are log
 
 ---
 
+## [2026-03-06] - Version 1.1.0
+
+### Added
+- `ai-sync-protocol.md` - Session start and post-change sync protocol
+- `_sync` section in `ai-context.schema.json` for auto-sync configuration
+- Forgejo fetch patterns in client skill template
+
+### Changed
+- Updated `client-skill.template.md` with central repository fetch instructions
+- Session now starts with sync check from Forgejo
+
+### Architecture
+- Central management from Abundance project
+- Single source of truth: Forgejo repo
+- Client projects self-sufficient via fetch from Forgejo
+
+---
+
 ## [2026-03-06] - Version 1.0.0
 
 ### Added

context/last-sync.json

@@ -1,13 +1,13 @@
 {
   "_meta": {
-    "last_updated": "2026-03-06T15:52:00Z",
+    "last_updated": "2026-03-06T16:30:00Z",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Timestamp tracking for context synchronization"
   },
-  "last_sync": "2026-03-06T15:52:00Z",
+  "last_sync": "2026-03-06T16:30:00Z",
-  "repository_url": "https://git.abundancepartners.app/abundance/ai-ops-templates",
+  "repository_url": "https://git.abundancepartners.app/matt/ai-ops-templates",
   "branch": "main",
-  "commit_hash": "initial",
+  "commit_hash": "v1.1.0",
   "files": {
     "templates": {
       "schema-product.json": "2026-03-06T15:52:00Z",
@@ -20,7 +20,8 @@
       "ui-fixes.json": "2026-03-06T15:52:00Z",
       "seo-rules.md": "2026-03-06T15:52:00Z",
       "common-fixes.md": "2026-03-06T15:52:00Z",
-      "ai-decision-guide.md": "2026-03-06T15:52:00Z"
+      "ai-decision-guide.md": "2026-03-06T15:52:00Z",
+      "ai-sync-protocol.md": "2026-03-06T16:30:00Z"
     },
     "snippets": {
       "add-internal-link.tsx": "2026-03-06T15:52:00Z",
@@ -36,7 +37,10 @@
     },
     "schemas": {
       "ai-cli.schema.json": "2026-03-06T15:52:00Z",
-      "ai-context.schema.json": "2026-03-06T15:52:00Z"
+      "ai-context.schema.json": "2026-03-06T16:30:00Z"
+    },
+    "skill-templates": {
+      "client-skill.template.md": "2026-03-06T16:30:00Z"
     }
   }
 }

schemas/ai-context.schema.json

@@ -4,8 +4,49 @@
   "title": "AI Context Manifest",
   "description": "Schema for per-project AI context manifest - the single source of truth for AI agents",
   "type": "object",
-  "required": ["client", "infrastructure"],
+  "required": ["client", "_sync"],
   "properties": {
+    "_sync": {
+      "type": "object",
+      "description": "Sync configuration for fetching context from central repository",
+      "required": ["templates_repo"],
+      "properties": {
+        "templates_repo": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the ai-ops-templates repository"
+        },
+        "last_check": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last sync check"
+        },
+        "auto_sync": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to automatically sync at session start"
+        },
+        "sync_interval_hours": {
+          "type": "integer",
+          "default": 24,
+          "minimum": 1,
+          "description": "Hours between automatic sync checks"
+        },
+        "preset_path": {
+          "type": "string",
+          "description": "Path to preset file (e.g., presets/slc-bride.json)"
+        },
+        "cached_context": {
+          "type": "object",
+          "description": "Locally cached context from last sync",
+          "properties": {
+            "brand": { "type": "object" },
+            "rules": { "type": "array", "items": { "type": "string" } },
+            "snippets": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "_meta": {
       "type": "object",
       "required": ["last_updated", "version"],

skill-templates/client-skill.template.md

@@ -1,11 +1,21 @@
 ---
 name: {{CLIENT_NAME}}
-description: Context and operations guide for {{CLIENT_NAME}} project. Use when working on {{DESCRIPTION}}.
+description: Context and operations guide for {{CLIENT_NAME}}. Fetches brand, patterns, and infrastructure from central ai-ops-templates repository.
 ---
 
 # {{CLIENT_NAME}}
 
-{{PROJECT_DESCRIPTION}}
+## Session Start Protocol
+
+**CRITICAL: Before starting work, sync context from Forgejo:**
+
+1. Read `.ai-context.json` in project root
+2. Check `_sync.last_check` timestamp
+3. If > 24 hours old or null, fetch fresh context:
+   - Brand preset: `https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{{CLIENT_SLUG}}.json`
+   - Common patterns: `https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/`
+
+---
 
 ## Project Overview
 
@@ -15,7 +25,23 @@ description: Context and operations guide for {{CLIENT_NAME}} project. Use when
 | **Site URL** | {{SITE_URL}} |
 | **Server** | {{SERVER_NAME}} ({{SERVER_IP}}) |
 | **Database** | {{DATABASE_NAME}} |
-| **Status** | {{PROJECT_STATUS}} |
+| **Preset URL** | `.../presets/{{CLIENT_SLUG}}.json` |
+
+---
+
+## Context Sources (Forgejo)
+
+All context is fetched from the central repository. Do NOT duplicate here.
+
+| Resource | Forgejo URL |
+|----------|-------------|
+| Brand Preset | `.../raw/main/presets/{{CLIENT_SLUG}}.json` |
+| UI Patterns | `.../raw/main/snippets/vendor-card.tsx` |
+| Schema Templates | `.../raw/main/templates/schema-product.json` |
+| SEO Rules | `.../raw/main/rules/seo-rules.md` |
+| Decision Guide | `.../raw/main/rules/ai-decision-guide.md` |
+
+**Base URL**: `https://git.abundancepartners.app/matt/ai-ops-templates`
 
 ---
 
@@ -26,45 +52,39 @@ description: Context and operations guide for {{CLIENT_NAME}} project. Use when
 # SSH into server
 ssh root@{{SERVER_IP}}
 
-# Or use abundance CLI
+# Or use abundance CLI (if installed)
 abundance srv ssh {{SERVER_NAME}}
 ```
 
 ### Coolify Deployment
 - **Dashboard**: {{COOLIFY_URL}}
 - **App ID**: {{COOLIFY_APP_ID}}
-- **Deploy**: `abundance coolify deploy application {{COOLIFY_APP_ID}}`
+- **Deploy via MCP**: `deploy_push({ target: "prod", app_id: "{{COOLIFY_APP_ID}}" })`
 
 ### Database
 ```bash
 # Query database
 abundance db query {{DATABASE_NAME}} "SELECT * FROM {{TABLE}} LIMIT 5"
 
-# Create SSH tunnel
+# Or use MCP
-abundance db tunnel {{DATABASE_NAME}}
+supabase_query({ query: "SELECT * FROM {{TABLE}} LIMIT $1", params: [5] })
 ```
 
 ---
 
-## Brand Guidelines
+## Brand Guidelines (Fetch from Forgejo)
 
-### Colors
+Brand colors, fonts, and styling are defined in:
+```
+https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{{CLIENT_SLUG}}.json
+```
+
+**Quick Reference** (verify against preset):
 | Color | Hex | Usage |
 |-------|-----|-------|
 | Primary | `{{PRIMARY_COLOR}}` | Buttons, links, highlights |
 | Secondary | `{{SECONDARY_COLOR}}` | Accents, badges |
 | Background | `{{BACKGROUND_COLOR}}` | Page background |
-| Text | `{{TEXT_COLOR}}` | Body text |
-
-### Typography
-- **Headings**: {{HEADING_FONT}}
-- **Body**: {{BODY_FONT}}
-
-### Tailwind Config
-Brand colors are defined in `presets/{{CLIENT_SLUG}}.json`. Reference via CSS variables:
-```css
-background-color: var(--primary);
-```
 
 ---
 
@@ -74,85 +94,49 @@ background-color: var(--primary);
 |-------|-------------|-----------|
 | {{ROUTE_1}} | {{ROUTE_1_DESC}} | `{{ROUTE_1_COMPONENT}}` |
 | {{ROUTE_2}} | {{ROUTE_2_DESC}} | `{{ROUTE_2_COMPONENT}}` |
-| {{ROUTE_3}} | {{ROUTE_3_DESC}} | `{{ROUTE_3_COMPONENT}}` |
 
 ---
 
-## Database Schema
+## Common Patterns (Fetch from Forgejo)
 
-### Key Tables
+Patterns are maintained centrally. Fetch as needed:
-| Table | Description | Key Columns |
-|-------|-------------|-------------|
-| {{TABLE_1}} | {{TABLE_1_DESC}} | {{TABLE_1_COLS}} |
-| {{TABLE_2}} | {{TABLE_2_DESC}} | {{TABLE_2_COLS}} |
 
-### Common Queries
+### Vendor Card
-```sql
+```
--- {{QUERY_1_DESC}}
+GET .../raw/main/snippets/vendor-card.tsx
-SELECT * FROM {{TABLE}} WHERE {{CONDITION}};
+```
+
+### Breadcrumb with Schema
+```
+GET .../raw/main/snippets/breadcrumb.tsx
+```
+
+### Schema Injection
+```
+GET .../raw/main/snippets/schema-inject.ts
 ```
 
 ---
 
-## APIs
+## Post-Change Sync
 
-### {{API_1_NAME}}
+After making changes that should be reusable:
-- **Base URL**: `{{API_1_URL}}`
+
-- **Auth**: {{API_1_AUTH}}
+1. Identify if change is client-specific or general pattern
-- **Env Key**: `{{API_1_ENV_KEY}}`
+2. If general, push to `ai-ops-templates` on Forgejo
+3. Update `context/last-sync.json` with timestamp
+4. Add entry to `context/CHANGELOG.md`
 
 ---
 
-## Common Patterns
+## Context Metadata
-
-### {{PATTERN_1_NAME}}
-```{{PATTERN_1_LANG}}
-{{PATTERN_1_CODE}}
-```
-
-### {{PATTERN_2_NAME}}
-```{{PATTERN_2_LANG}}
-{{PATTERN_2_CODE}}
-```
-
----
-
-## Integrations
-
-| Service | Purpose | Config Location |
-|---------|---------|-----------------|
-| {{SERVICE_1}} | {{SERVICE_1_PURPOSE}} | {{SERVICE_1_CONFIG}} |
-| {{SERVICE_2}} | {{SERVICE_2_PURPOSE}} | {{SERVICE_2_CONFIG}} |
-
----
-
-## Troubleshooting
-
-### {{ISSUE_1}}
-**Symptom**: {{ISSUE_1_SYMPTOM}}
-**Solution**: {{ISSUE_1_SOLUTION}}
-
-### {{ISSUE_2}}
-**Symptom**: {{ISSUE_2_SYMPTOM}}
-**Solution**: {{ISSUE_2_SOLUTION}}
-
----
-
-## Recent Changes
-
-| Date | Change | Notes |
-|------|--------|-------|
-| {{DATE_1}} | {{CHANGE_1}} | {{NOTES_1}} |
-
----
-
-## Context Metadata (Auto-Updated)
 
 | Field | Value |
 |-------|-------|
 | _last_updated | {{LAST_UPDATED}} |
 | _version | {{VERSION}} |
-| _synced_from | git.abundancepartners.app/abundance/ai-ops-templates |
+| _sync_repo | `https://git.abundancepartners.app/matt/ai-ops-templates` |
+| _preset | `presets/{{CLIENT_SLUG}}.json` |
 
 ---
 
@@ -165,9 +149,18 @@ abundance srv status
 # View logs
 abundance docker logs {{SERVER_NAME}} {{CONTAINER}} -f --tail 100
 
-# Deploy to staging
+# Deploy via MCP
-deploy_push({ target: "staging", app_id: "{{STAGING_APP_ID}}" })
+deploy_push({ target: "prod", app_id: "{{COOLIFY_APP_ID}}" })
 
-# Deploy to production
+# Fetch fresh context
-deploy_push({ target: "prod", app_id: "{{PROD_APP_ID}}" })
+# Read .ai-context.json, then fetch preset from Forgejo
 ```
+
+---
+
+## Self-Healing
+
+If context seems wrong:
+1. Force refresh: Set `_sync.last_check` to null in `.ai-context.json`
+2. Fetch fresh preset from Forgejo
+3. Verify against `.../raw/main/presets/{{CLIENT_SLUG}}.json`