Add repeatable resource cycle runbook and one-command script

README.md

@@ -37,6 +37,7 @@ This repository now has a machine-readable and searchable resource pipeline:
 - Search data export: [docs/search/resources.json](docs/search/resources.json)
 - Full index docs: [docs/resource_catalog.md](docs/resource_catalog.md)
 - Automation docs: [docs/resource_automation.md](docs/resource_automation.md)
+- Repeatable runbook: [docs/resource_cycle_runbook.md](docs/resource_cycle_runbook.md)
 
 ## How New Resources Are Added
 
@@ -55,6 +56,9 @@ The process is semi-automatic:
 - Run `python scripts/generate_resource_views.py`
 - Commit generated updates (`resources/*/README.md` and `docs/search/resources.json`).
 
+Shortcut wrapper:
+- Run `python scripts/run_resource_cycle.py --limit 25`
+
 This prevents low-confidence links from being merged directly while still automating discovery.
 
 ## Quickstart

docs/README.md

@@ -20,6 +20,7 @@ This folder is the main documentation entry point for contributors.
 - Platforms and publish flow: [platforms.md](platforms.md)
 - GitHub operations: [github_operations.md](github_operations.md)
 - Resource automation: [resource_automation.md](resource_automation.md)
+- Resource cycle runbook: [resource_cycle_runbook.md](resource_cycle_runbook.md)
 
 ## Resource tracking
 - Master resource index: [resource_catalog.md](resource_catalog.md)

docs/resource_automation.md

@@ -17,6 +17,7 @@ This repository uses a semi-automated process to keep Pashto resources current w
 - Validate catalog: `python scripts/validate_resource_catalog.py`
 - Generate markdown and search index: `python scripts/generate_resource_views.py`
 - Sync new candidates: `python scripts/sync_resources.py --limit 20`
+- Full run wrapper: `python scripts/run_resource_cycle.py --limit 25`
 
 ## GitHub Actions
 - CI (`.github/workflows/ci.yml`) enforces:
@@ -34,3 +35,6 @@ This repository uses a semi-automated process to keep Pashto resources current w
    - `python scripts/validate_resource_catalog.py`
    - `python scripts/generate_resource_views.py`
 5. Commit and open PR.
+
+## Runbook
+- Reusable process guide: [resource_cycle_runbook.md](resource_cycle_runbook.md)

docs/resource_cycle_runbook.md

@@ -0,0 +1,43 @@
+# Resource Cycle Runbook
+
+Use this runbook whenever you want to repeat the resource update process without re-explaining it.
+
+## Weekly automation (already enabled)
+- Workflow: [../.github/workflows/resource_sync.yml](../.github/workflows/resource_sync.yml)
+- Schedule: every Monday (UTC) via GitHub Actions cron.
+- Output: updates [../resources/catalog/pending_candidates.json](../resources/catalog/pending_candidates.json) and opens a review PR.
+
+## Manual run (single command)
+Run from repository root:
+
+```bash
+python scripts/run_resource_cycle.py --limit 25
+```
+
+What it executes:
+1. `python scripts/sync_resources.py --limit 25`
+2. `python scripts/validate_resource_catalog.py`
+3. `python scripts/generate_resource_views.py`
+4. `python scripts/check_links.py`
+5. `python -m pytest -q`
+
+## Discovery-only mode
+If you only want fresh candidates:
+
+```bash
+python scripts/run_resource_cycle.py --discover-only --limit 25
+```
+
+## Promotion step (manual review)
+After discovery, promote only approved resources:
+1. Open [../resources/catalog/pending_candidates.json](../resources/catalog/pending_candidates.json).
+2. Copy selected entries into [../resources/catalog/resources.json](../resources/catalog/resources.json).
+3. Ensure unique `id` and valid evidence fields.
+4. Re-run:
+   - `python scripts/run_resource_cycle.py --skip-pytest`
+5. Commit and push.
+
+## Guardrails
+- Do not auto-promote candidates without evidence and license review.
+- Keep `status: verified` only for reviewed entries.
+- Generated files must be committed after catalog updates.

scripts/README.md

@@ -8,6 +8,7 @@ Automation scripts for quality checks, resource catalog validation, and search i
 - `validate_resource_catalog.py`: validate `resources/catalog/resources.json`.
 - `generate_resource_views.py`: generate `resources/*/README.md`, `resources/README.md`, and `docs/search/resources.json` from the catalog.
 - `sync_resources.py`: collect new candidate Pashto resources from public endpoints into `resources/catalog/pending_candidates.json`.
+- `run_resource_cycle.py`: run the full repeatable resource cycle with one command.
 
 ## Usage
 
@@ -31,6 +32,16 @@ Sync candidate resources for maintainer review:
 python scripts/sync_resources.py --limit 20
 ```
 
+Run full repeatable cycle:
+```bash
+python scripts/run_resource_cycle.py --limit 25
+```
+
+Run discovery only:
+```bash
+python scripts/run_resource_cycle.py --discover-only --limit 25
+```
+
 Check markdown links format:
 ```bash
 python scripts/check_links.py

scripts/run_resource_cycle.py

@@ -0,0 +1,69 @@
+"""Run the Pashto resource update cycle in a repeatable way.
+
+This script is a command wrapper around existing resource scripts so maintainers
+do not need to remember the full sequence.
+
+Usage:
+    python scripts/run_resource_cycle.py
+    python scripts/run_resource_cycle.py --limit 30
+    python scripts/run_resource_cycle.py --skip-pytest
+    python scripts/run_resource_cycle.py --discover-only
+"""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _run(command: list[str], cwd: Path) -> int:
+    print(f"[run] {shlex.join(command)}")
+    completed = subprocess.run(command, cwd=str(cwd), check=False)
+    return completed.returncode
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--limit", type=int, default=25, help="Candidate fetch limit per source")
+    parser.add_argument("--skip-pytest", action="store_true", help="Skip pytest step")
+    parser.add_argument("--discover-only", action="store_true", help="Only sync candidates and stop")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[1]
+    steps: list[list[str]] = [
+        ["python", "scripts/sync_resources.py", "--limit", str(args.limit)],
+    ]
+
+    if not args.discover_only:
+        steps.extend(
+            [
+                ["python", "scripts/validate_resource_catalog.py"],
+                ["python", "scripts/generate_resource_views.py"],
+                ["python", "scripts/check_links.py"],
+            ]
+        )
+        if not args.skip_pytest:
+            steps.append(["python", "-m", "pytest", "-q"])
+
+    for command in steps:
+        code = _run(command, repo_root)
+        if code != 0:
+            print(f"[fail] Step failed with exit code {code}")
+            return code
+
+    print("[ok] Resource cycle completed")
+    if args.discover_only:
+        print(
+            "Next: review resources/catalog/pending_candidates.json and promote approved "
+            "entries into resources/catalog/resources.json."
+        )
+    else:
+        print("Next: commit updated catalog/generated files and push.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())