docs/platform_sync_policy.md

# Platform Sync Policy (GitHub and Hugging Face)

This project is mirrored on two platforms:

- GitHub: `Musawer1214/pashto-language-resources`
- Hugging Face: `Musawer14/pashto-language-resources`

The goal is to keep content equivalent while respecting platform differences.

## Canonical Flow

1. Make and validate changes locally.
2. Push to GitHub `main` first.
3. Sync the resulting content snapshot to Hugging Face `main`.

## Compatibility Rules

- Avoid committing large binary files directly when syncing to Hugging Face.
- Prefer URL-hosted images in docs when possible.
- Keep absolute links pinned to the final slug `pashto-language-resources`.
- Keep one shared `README.md` that is valid on both platforms.

## Shared Markdown Subset (GitHub + Hugging Face)

Use a lowest-common-denominator style in shared docs:

- Standard Markdown headings, bullet lists, links, and fenced code blocks.
- Relative links for internal files whenever possible.
- YAML front matter only where needed (`README.md` for HF metadata, docs pages for Jekyll SEO).
- Avoid GitHub-only HTML widgets and avoid HF-specific custom blocks in shared files.
## Known Platform Differences

- GitHub accepts regular Git binary blobs in many repos.
- Hugging Face may reject binary blobs unless stored with Xet/LFS-compatible flow.
- Hugging Face may warn about missing model-card metadata in README; this is a warning, not a push blocker.

## Safe Update Checklist

1. Run checks:
   - `python scripts/check_links.py`
   - `python scripts/validate_resource_catalog.py`
   - `python -m pytest -q`
2. Confirm slug links:
   - `rg -n "pashto-language-resources" README.md docs pyproject.toml`
3. Push GitHub:
   - `git push origin main`
4. Push Hugging Face:
   - `git push hf <sync-branch>:main`
5. Verify both remotes:
   - `git ls-remote origin refs/heads/main`
   - `git ls-remote hf refs/heads/main`

## Conflict Handling

If GitHub and Hugging Face histories diverge:

- Keep GitHub `main` as canonical source history.
- Sync Hugging Face using a content snapshot commit based on `hf/main`.
- Do not rewrite remote history unless explicitly required.