@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_Engine/tests/test_worker_and_cleanup.py

@@ -0,0 +1,541 @@
+"""Tests for omega_engine.worker (persistent-tmux dispatch) and
+omega_engine.cleanup (OmegaOS-adapted disk cleanup).
+
+The worker tests mock both ``tmux`` and ``claude``: the real binaries are
+not on the test runner so we exercise the brief I/O, the model resolution,
+the JSON-parse → ``.done.json`` path, and the status/list helpers.
+
+The cleanup tests build a fake ``$OMEGA_HOME`` tree under ``tempfile`` and
+assert per-tier bytes_freed / items_removed counts in dry-run AND real
+modes.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+from omega_engine import worker as W  # noqa: E402
+from omega_engine import cleanup as C  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Worker — model defaults
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultModel(unittest.TestCase):
+    def test_worker_role_picks_opus_1m(self):
+        self.assertEqual(W.default_model_for_role("worker"),
+                         "claude-opus-4-7[1m]")
+
+    def test_construct_role_picks_opus_1m(self):
+        self.assertEqual(W.default_model_for_role("construct"),
+                         "claude-opus-4-7[1m]")
+
+    def test_oracle_role_picks_sonnet(self):
+        self.assertEqual(W.default_model_for_role("oracle"), "sonnet")
+
+    def test_manager_role_picks_sonnet(self):
+        self.assertEqual(W.default_model_for_role("manager"), "sonnet")
+
+    def test_audit_role_picks_sonnet(self):
+        self.assertEqual(W.default_model_for_role("audit"), "sonnet")
+
+    def test_classifier_role_picks_haiku(self):
+        self.assertEqual(W.default_model_for_role("classifier"), "haiku")
+
+    def test_unknown_role_falls_back_to_sonnet(self):
+        self.assertEqual(W.default_model_for_role("does-not-exist"), "sonnet")
+
+
+class TestWorkerBrief(unittest.TestCase):
+    def test_resolved_model_uses_role_default(self):
+        b = W.WorkerBrief(task_id="t1", role="worker", intent="x")
+        self.assertEqual(b.resolved_model(), "claude-opus-4-7[1m]")
+
+    def test_explicit_model_overrides_role_default(self):
+        b = W.WorkerBrief(task_id="t1", role="worker", intent="x", model="haiku")
+        self.assertEqual(b.resolved_model(), "haiku")
+
+    def test_oracle_role_resolved_to_sonnet(self):
+        b = W.WorkerBrief(task_id="t1", role="oracle", intent="x")
+        self.assertEqual(b.resolved_model(), "sonnet")
+
+    def test_round_trip_json(self):
+        b = W.WorkerBrief(
+            task_id="t1", role="worker", intent="hello",
+            system_prompt="sys", user_prompt="usr",
+            project="myproj", cwd="/tmp",
+            verify_cmd="true", mission_id="m1",
+        )
+        loaded = W.WorkerBrief.from_dict(json.loads(b.to_json()))
+        self.assertEqual(loaded.task_id, "t1")
+        self.assertEqual(loaded.role, "worker")
+        self.assertEqual(loaded.user_prompt, "usr")
+        self.assertEqual(loaded.system_prompt, "sys")
+        self.assertEqual(loaded.project, "myproj")
+        self.assertEqual(loaded.cwd, "/tmp")
+        self.assertEqual(loaded.verify_cmd, "true")
+        self.assertEqual(loaded.mission_id, "m1")
+
+    def test_user_prompt_falls_back_to_intent_in_json(self):
+        b = W.WorkerBrief(task_id="t1", role="worker", intent="just do it")
+        data = json.loads(b.to_json())
+        self.assertEqual(data["user_prompt"], "just do it")
+
+
+class TestBriefIO(unittest.TestCase):
+    def test_write_and_read_brief(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(task_id="t-test", role="worker", intent="hi")
+            p = W.write_brief(home, brief)
+            self.assertTrue(p.exists())
+            # private session dir
+            self.assertEqual(oct(p.parent.stat().st_mode)[-3:], "700")
+            loaded = W.read_brief(home, "t-test")
+            self.assertEqual(loaded.task_id, "t-test")
+            self.assertEqual(loaded.intent, "hi")
+
+    def test_read_brief_missing_raises(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(FileNotFoundError):
+                W.read_brief(Path(tmp), "no-such-task")
+
+
+# ---------------------------------------------------------------------------
+# Worker — spawn (mocked tmux)
+# ---------------------------------------------------------------------------
+
+
+def _fake_proc(stdout: str = "", returncode: int = 0, stderr: str = ""):
+    """Build a fake subprocess.CompletedProcess."""
+    import subprocess
+    return subprocess.CompletedProcess(
+        args=[], returncode=returncode, stdout=stdout, stderr=stderr,
+    )
+
+
+class TestSpawn(unittest.TestCase):
+    def test_spawn_writes_brief_and_calls_tmux(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(
+                task_id="t-spawn", role="worker", intent="x",
+                project="Test",
+            )
+            calls = []
+
+            def fake_run(cmd, **kw):
+                calls.append(cmd)
+                # has-session must return non-zero (no existing session)
+                if cmd[:2] == ["tmux", "has-session"]:
+                    return _fake_proc(returncode=1)
+                return _fake_proc()
+
+            with mock.patch.object(W.shutil, "which",
+                                   side_effect=lambda x: f"/fake/{x}"):
+                with mock.patch.object(W.subprocess, "run", side_effect=fake_run):
+                    name = W.spawn_worker(brief, home=home, worker_id=2)
+            # Brief written
+            self.assertTrue((home / "Agentik_Runtime" / "sessions"
+                             / "t-spawn" / "brief.json").exists())
+            # tmux new-session called
+            new_calls = [c for c in calls if c[:2] == ["tmux", "new-session"]]
+            self.assertEqual(len(new_calls), 1)
+            self.assertIn("Test-worker-2-x", name)
+            self.assertIn("Test-worker-2-x", new_calls[0])
+
+    def test_spawn_is_idempotent_if_session_exists(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(task_id="t-idem", role="worker", intent="x")
+
+            def fake_run(cmd, **kw):
+                if cmd[:2] == ["tmux", "has-session"]:
+                    return _fake_proc(returncode=0)  # exists
+                self.fail(f"unexpected tmux call: {cmd}")
+
+            with mock.patch.object(W.shutil, "which",
+                                   side_effect=lambda x: f"/fake/{x}"):
+                with mock.patch.object(W.subprocess, "run", side_effect=fake_run):
+                    name = W.spawn_worker(brief, home=home, worker_id=1)
+            self.assertIn("worker-1-x", name)
+
+    def test_spawn_raises_without_tmux(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.object(W.shutil, "which", return_value=None):
+                with self.assertRaises(RuntimeError):
+                    W.spawn_worker(
+                        W.WorkerBrief(task_id="t", role="worker", intent="x"),
+                        home=Path(tmp),
+                    )
+
+
+# ---------------------------------------------------------------------------
+# Worker — run_brief (mocked claude)
+# ---------------------------------------------------------------------------
+
+
+class TestRunBrief(unittest.TestCase):
+    def test_happy_path_writes_done_clean(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(
+                task_id="t-run", role="worker", intent="reply orange",
+                user_prompt="reply orange",
+            )
+            W.write_brief(home, brief)
+            claude_json = json.dumps({
+                "result": "orange",
+                "session_id": "sess-123",
+                "total_cost_usd": 0.0012,
+                "usage": {"input_tokens": 10, "output_tokens": 1},
+            })
+            with mock.patch.object(W.subprocess, "run",
+                                   return_value=_fake_proc(stdout=claude_json)):
+                rc = W.run_brief(home, "t-run")
+            self.assertEqual(rc, 0)
+            done = json.loads(
+                (home / "Agentik_Runtime" / "sessions" / "t-run"
+                 / ".done.json").read_text()
+            )
+            self.assertEqual(done["status"], "done_clean")
+            self.assertEqual(done["summary"], "orange")
+            self.assertEqual(done["artifacts"]["session_id"], "sess-123")
+            self.assertEqual(
+                done["artifacts"]["model"], "claude-opus-4-7[1m]"
+            )
+            self.assertAlmostEqual(
+                done["artifacts"]["usage"]["cost_usd"], 0.0012, places=4,
+            )
+
+    def test_claude_nonzero_writes_failed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(task_id="t-fail", role="worker", intent="x")
+            W.write_brief(home, brief)
+            with mock.patch.object(W.subprocess, "run",
+                                   return_value=_fake_proc(
+                                       returncode=1, stderr="boom")):
+                rc = W.run_brief(home, "t-fail")
+            self.assertEqual(rc, 1)
+            done = json.loads(
+                (home / "Agentik_Runtime" / "sessions" / "t-fail"
+                 / ".done.json").read_text()
+            )
+            self.assertEqual(done["status"], "failed")
+            self.assertIn("boom", done["errors"][0])
+
+    def test_missing_brief_writes_failed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            rc = W.run_brief(home, "t-missing")
+            self.assertEqual(rc, 1)
+            done = json.loads(
+                (home / "Agentik_Runtime" / "sessions" / "t-missing"
+                 / ".done.json").read_text()
+            )
+            self.assertEqual(done["status"], "failed")
+            self.assertIn("missing brief", done["summary"])
+
+    def test_non_json_response_writes_failed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            brief = W.WorkerBrief(task_id="t-nj", role="worker", intent="x")
+            W.write_brief(home, brief)
+            with mock.patch.object(W.subprocess, "run",
+                                   return_value=_fake_proc(stdout="<html>not-json")):
+                rc = W.run_brief(home, "t-nj")
+            self.assertEqual(rc, 1)
+            done = json.loads(
+                (home / "Agentik_Runtime" / "sessions" / "t-nj"
+                 / ".done.json").read_text()
+            )
+            self.assertEqual(done["status"], "failed")
+            self.assertIn("non-JSON", done["summary"])
+
+
+class TestStatusAndList(unittest.TestCase):
+    def test_status_reads_done_json(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            sess = home / "Agentik_Runtime" / "sessions" / "t-stat"
+            sess.mkdir(parents=True)
+            (sess / ".done.json").write_text(json.dumps({
+                "status": "done_clean", "summary": "ok",
+                "artifacts": {"model": "sonnet"},
+            }))
+            s = W.worker_status(home, "t-stat")
+            self.assertEqual(s["state"], "done_clean")
+            self.assertEqual(s["source"], ".done.json")
+
+    def test_status_absent_when_nothing(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.object(W.shutil, "which", return_value=None):
+                s = W.worker_status(Path(tmp), "no-such")
+            self.assertEqual(s["state"], "unknown")
+
+    def test_list_workers_skips_dirs_without_brief(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            sess = home / "Agentik_Runtime" / "sessions"
+            (sess / "t-a").mkdir(parents=True)
+            (sess / "t-a" / "brief.json").write_text(json.dumps({
+                "task_id": "t-a", "role": "worker", "intent": "do A",
+            }))
+            (sess / "t-b").mkdir()  # no brief
+            with mock.patch.object(W.shutil, "which", return_value=None):
+                rows = W.list_workers(home)
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(rows[0]["task_id"], "t-a")
+            self.assertEqual(rows[0]["role"], "worker")
+            self.assertEqual(rows[0]["model"], "claude-opus-4-7[1m]")
+
+    def test_wait_for_done_returns_immediately_on_done(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            sess = home / "Agentik_Runtime" / "sessions" / "t-w"
+            sess.mkdir(parents=True)
+            (sess / ".done.json").write_text(
+                json.dumps({"status": "done_clean"})
+            )
+            t0 = time.time()
+            s = W.wait_for_done(home, "t-w", timeout_s=10, poll_s=1)
+            self.assertLess(time.time() - t0, 2)
+            self.assertEqual(s["state"], "done_clean")
+
+    def test_wait_for_done_times_out(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.object(W.shutil, "which", return_value=None):
+                s = W.wait_for_done(Path(tmp), "no-task", timeout_s=1, poll_s=1)
+            self.assertEqual(s["state"], "timeout")
+
+
+# ---------------------------------------------------------------------------
+# Cleanup — tier helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_fake_home(tmpdir: Path) -> Path:
+    """Build a minimal $OMEGA_HOME tree with all the dirs the cleaner touches."""
+    home = tmpdir / "Omega"
+    for sub in [
+        "Agentik_Runtime/sessions",
+        "Agentik_Runtime/eventlog",
+        "Agentik_Runtime/memory",
+        "Agentik_Extra/var/tmp",
+        "Agentik_Extra/var/cache",
+        "Agentik_Extra/var/logs",
+        "Agentik_Extra/staging/promotion",
+        "Agentik_Coding/projects",
+    ]:
+        (home / sub).mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def _set_mtime(p: Path, days_ago: float) -> None:
+    t = time.time() - days_ago * 86400
+    os.utime(p, (t, t))
+
+
+class TestTier2Scratch(unittest.TestCase):
+    def test_removes_old_var_tmp_entries(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            old = home / "Agentik_Extra" / "var" / "tmp" / "stale"
+            old.mkdir()
+            (old / "x").write_text("x" * 1024)
+            _set_mtime(old, 5)
+            recent = home / "Agentik_Extra" / "var" / "tmp" / "fresh"
+            recent.mkdir()
+            (recent / "y").write_text("y" * 1024)
+            # Dry-run first
+            r = C.tier2_scratch(home, dry_run=True)
+            self.assertGreaterEqual(r.items_removed, 1)
+            self.assertTrue(old.exists())
+            # Real
+            r = C.tier2_scratch(home, dry_run=False)
+            self.assertFalse(old.exists())
+            self.assertTrue(recent.exists())
+
+    def test_skips_recent_var_cache(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            recent = home / "Agentik_Extra" / "var" / "cache" / "today"
+            recent.mkdir()
+            (recent / "z").write_text("z")
+            r = C.tier2_scratch(home, dry_run=False)
+            self.assertEqual(r.items_removed, 0)
+            self.assertTrue(recent.exists())
+
+
+class TestTier3Runtime(unittest.TestCase):
+    def test_delegates_to_prune_and_aggregates(self):
+        # Just verify it returns a report without erroring on an empty home.
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            r = C.tier3_runtime(home, older_than_days=30, dry_run=True)
+            self.assertEqual(r.tier, "3 runtime DBs+sessions")
+            self.assertEqual(r.items_removed, 0)
+            self.assertIn("events", r.detail)
+            self.assertIn("sessions", r.detail)
+
+
+class TestTier5NodeModules(unittest.TestCase):
+    def test_removes_node_modules_for_idle_project(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            # Idle project
+            idle = home / "Agentik_Coding" / "projects" / "idle-proj"
+            idle.mkdir()
+            (idle / "README.md").write_text("hello")
+            _set_mtime(idle / "README.md", 14)
+            _set_mtime(idle, 14)
+            nm = idle / "node_modules"
+            nm.mkdir()
+            (nm / "pkg").write_text("a" * 2048)
+            # Active project
+            active = home / "Agentik_Coding" / "projects" / "active-proj"
+            active.mkdir()
+            (active / "main.py").write_text("# hi")
+            anm = active / "node_modules"
+            anm.mkdir()
+            (anm / "pkg").write_text("b" * 1024)
+
+            # Dry-run
+            r = C.tier5_node_modules(home, idle_days=7, dry_run=True)
+            self.assertEqual(r.items_removed, 1)
+            self.assertIn("active-proj", r.skipped)
+            self.assertTrue(nm.exists())
+
+            # Real
+            r = C.tier5_node_modules(home, idle_days=7, dry_run=False)
+            self.assertEqual(r.items_removed, 1)
+            self.assertFalse(nm.exists())
+            self.assertTrue(anm.exists())
+
+    def test_no_projects_returns_empty(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            r = C.tier5_node_modules(home, idle_days=7, dry_run=False)
+            self.assertEqual(r.items_removed, 0)
+
+
+class TestTier6Logs(unittest.TestCase):
+    def test_truncates_oversized_log_keeps_tail(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            log = home / "Agentik_Extra" / "var" / "logs" / "big.log"
+            # 30 MB to trigger truncation (default threshold is 20 MB)
+            content = (b"x" * 1024) * 30 * 1024
+            log.write_bytes(content)
+            r = C.tier6_logs(home, max_log_mb=20, keep_tail_mb=1, dry_run=False)
+            self.assertEqual(r.items_removed, 1)
+            # File still exists, size around 1 MB
+            self.assertTrue(log.exists())
+            self.assertLessEqual(log.stat().st_size, 2 * 1024 * 1024)
+
+    def test_small_logs_untouched(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            log = home / "Agentik_Extra" / "var" / "logs" / "small.log"
+            log.write_bytes(b"tiny")
+            r = C.tier6_logs(home, max_log_mb=20, dry_run=False)
+            self.assertEqual(r.items_removed, 0)
+            self.assertEqual(log.read_bytes(), b"tiny")
+
+
+class TestDeepStaging(unittest.TestCase):
+    def test_removes_old_insights_only(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            staging = home / "Agentik_Extra" / "staging" / "promotion"
+            old = staging / "insight-old.json"
+            old.write_text("{}")
+            _set_mtime(old, 30)
+            fresh = staging / "insight-fresh.json"
+            fresh.write_text("{}")
+            r = C.deep_staging(home, older_than_days=14, dry_run=False)
+            self.assertEqual(r.items_removed, 1)
+            self.assertFalse(old.exists())
+            self.assertTrue(fresh.exists())
+
+
+class TestDeepTranscripts(unittest.TestCase):
+    def test_drops_completed_old_transcripts_only(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            sess_root = home / "Agentik_Runtime" / "sessions"
+            # Completed + old → eligible
+            done_old = sess_root / "t-old"
+            done_old.mkdir()
+            (done_old / ".done.json").write_text("{}")
+            tr = done_old / "transcript.json"
+            tr.write_text("x" * 4096)
+            _set_mtime(tr, 14)
+            # Completed + fresh → keep
+            done_new = sess_root / "t-new"
+            done_new.mkdir()
+            (done_new / ".done.json").write_text("{}")
+            tr2 = done_new / "transcript.json"
+            tr2.write_text("y" * 100)
+            # In-flight (no .done.json) → keep
+            inflight = sess_root / "t-inflight"
+            inflight.mkdir()
+            tr3 = inflight / "transcript.json"
+            tr3.write_text("z" * 4096)
+            _set_mtime(tr3, 30)
+            r = C.deep_transcripts(home, older_than_days=7, dry_run=False)
+            self.assertEqual(r.items_removed, 1)
+            self.assertFalse(tr.exists())
+            self.assertTrue(tr2.exists())
+            self.assertTrue(tr3.exists())  # in-flight stays
+
+
+class TestCleanupOrchestrator(unittest.TestCase):
+    def test_dry_run_returns_reports_no_disk_change(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            (home / "Agentik_Extra" / "var" / "tmp" / "scratch").mkdir()
+            _set_mtime(home / "Agentik_Extra" / "var" / "tmp" / "scratch", 5)
+            reports = C.cleanup(home, dry_run=True, deep=False)
+            # 6 tiers, no deep
+            self.assertEqual(len(reports), 6)
+            self.assertTrue(all(r.dry_run for r in reports))
+            # scratch dir still present
+            self.assertTrue(
+                (home / "Agentik_Extra" / "var" / "tmp" / "scratch").exists()
+            )
+
+    def test_deep_runs_extra_tiers(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            reports = C.cleanup(home, dry_run=True, deep=True)
+            # 6 base + 5 deep
+            self.assertEqual(len(reports), 11)
+            deep_tiers = [r for r in reports if r.tier.startswith("D ")]
+            self.assertEqual(len(deep_tiers), 5)
+
+    def test_format_summary_includes_total(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = _make_fake_home(Path(tmp))
+            reports = C.cleanup(home, dry_run=True)
+            text = C.format_summary(reports, home)
+            self.assertIn("OmegaOS cleanup", text)
+            self.assertIn("total freed", text)
+            self.assertIn(str(home), text)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/omega/Agentik_Extra/etc/secrets/.vault-key

@@ -0,0 +1,3 @@
+# created: 2026-05-23T12:06:13Z
+# public key: age1vt9qtm4tg6am23lp88ja5cdxl9jnn7cdhuyp39yh76f3wken2dpskukvt4
+AGE-SECRET-KEY-1GGNKC2Q3APMD9H632N38HETTAHM9EJPCFMRJHYF3H34HWQCVL60QG5AHVP

package/omega/Agentik_Extra/etc/secrets/.vault-pub

@@ -0,0 +1 @@
+age1vt9qtm4tg6am23lp88ja5cdxl9jnn7cdhuyp39yh76f3wken2dpskukvt4

package/omega/Agentik_SSOT/VERSION

@@ -1 +1 @@
-0.1.0
+0.19.6

package/omega/Agentik_SSOT/claude-plugins/claude-plugins.yaml

@@ -0,0 +1,100 @@
+# Omega OS — Claude Code plugin catalog.
+#
+# The installer's 45-claude-plugins step reads this file to present a checklist
+# (interactive) or apply the manifest's `claude_plugins:` list (headless). For
+# each selected plugin, the installer:
+#
+#   1. ensures the marketplace is registered: `claude plugin marketplace add <source>`
+#      (skipped if `source: builtin` — already present after a fresh install)
+#   2. installs it:                          `claude plugin install <name>@<marketplace> -s <scope>`
+#
+# Maintained by the claudecode-educator (Agentik_Orchestration/educators/).
+# Secrets are referenced by name only — never stored here.
+#
+# Marketplaces are listed once; plugins reference them by `marketplace:` id.
+
+version: 1
+
+marketplaces:
+  - id: claude-plugins-official
+    source: "github:anthropics/claude-plugins-official"
+    description: "Anthropic's official plugin marketplace"
+    builtin: true
+  - id: anthropic-skills
+    source: "github:anthropics/skills"
+    description: "Anthropic's official skill collection (find-skills, document skills, etc.)"
+    builtin: false
+    trust: high
+  - id: vercel-labs-skills
+    source: "github:vercel-labs/skills"
+    description: "Vercel Labs skills (skill discovery CLI + find-skills)"
+    builtin: false
+    trust: high
+  - id: davila7-templates
+    source: "github:davila7/claude-code-templates"
+    description: "Community-maintained Claude Code templates and skills"
+    builtin: false
+    trust: medium
+  - id: thedotmack
+    source: "github:thedotmack/claude-mem"
+    description: "claude-mem memory + observation system"
+    builtin: false
+    trust: medium
+
+catalog:
+  - id: claude-mem
+    name: claude-mem
+    description: "Long-term memory + observation system across sessions"
+    category: memory
+    marketplace: thedotmack
+    scope: user
+    recommended: true
+
+  - id: frontend-design
+    name: frontend-design
+    description: "Frontend UI/UX patterns and component scaffolding"
+    category: ui
+    marketplace: claude-plugins-official
+    scope: user
+    recommended: true
+
+  - id: playground
+    name: playground
+    description: "Interactive playground for experimenting with plugins"
+    category: dev
+    marketplace: claude-plugins-official
+    scope: user
+    recommended: false
+
+  - id: stripe
+    name: stripe
+    description: "Stripe payments — products, prices, subscriptions, webhooks"
+    category: integrations
+    marketplace: claude-plugins-official
+    scope: project
+    secrets: [STRIPE_SECRET_KEY]
+    recommended: false
+
+  - id: skill-creator
+    name: skill-creator
+    description: "Generate new SKILL.md files with Claude's help (Anthropic official)"
+    category: meta
+    marketplace: anthropic-skills
+    scope: user
+    recommended: true
+
+  - id: find-skills
+    name: find-skills
+    description: "Discover skills across marketplaces (vercel-labs); pairs with skill-auditor"
+    category: meta
+    marketplace: vercel-labs-skills
+    scope: user
+    recommended: true
+
+  - id: document-skills
+    name: document-skills
+    description: "Anthropic official suite — docx, pdf, pptx, xlsx (creation + editing)"
+    category: documents
+    marketplace: anthropic-skills
+    scope: user
+    recommended: true