From 1f67aaab6329f0bb0c708d839a468ebcf504903a Mon Sep 17 00:00:00 2001
From: salvacybersec <salva@opsecti.local>
Date: Sun, 19 Apr 2026 01:35:18 +0300
Subject: [PATCH] refine: README + opc-skills binary iteration

Post-initial commit refinement of the standalone opc tool.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md      | 11 +++++++++++
 bin/opc-skills | 12 ++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/README.md b/README.md
index 93ea421..2bffa15 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,17 @@ opc-skills reindex                    # rebuild INDEX.json / INDEX.md
 
 `fzf` is required for the interactive commands.
 
+## Shared reference files
+
+Some skills reference sibling files via `../<name>.md` (e.g. the 20 Feynman research skills use `../_platform-mapping.md` for cross-platform tool mapping). `opc-skills enable` auto-syncs any such files from PARKED → ACTIVE so the relative references keep resolving.
+
+Currently synced:
+- `_platform-mapping.md` — Feynman-skills cross-platform subagent/scheduling/persistence mapping
+
+If you add new shared-reference files at the PARKED root, extend `sync_shared_refs()` in `bin/opc-skills`.
+
 ## Known interaction
 
 The `personas` repo's `build.py --install opencode` currently wipes and repopulates `~/.config/opencode/skills/` as part of installation, which destroys the active set curated here. Use `opc-skills` *after* any personas install, or skip the skills half of `build.py` installs.
+
+`build.py --install opencode` and `build.py --install claude-skills` both emit `_platform-mapping.md` at the skills-root alongside the 20 Feynman skills (`deep-research`, `literature-review`, `paper-code-audit`, `peer-review`, `paper-writing`, `replication`, `source-comparison`, `summarize`, `alpha-research`, `eli5`, `autoresearch`, `docker`, `modal-compute`, `runpod-compute`, `session-log`, `session-search`, `jobs`, `watch`, `preview`, `contributing`).
diff --git a/bin/opc-skills b/bin/opc-skills
index 7b8e643..c37566b 100755
--- a/bin/opc-skills
+++ b/bin/opc-skills
@@ -54,6 +54,17 @@ ensure_fzf() {
   command -v fzf >/dev/null || { echo "fzf is required for this command" >&2; exit 1; }
 }
 
+# Sync loose sibling files (e.g. _platform-mapping.md) from PARKED → ACTIVE so
+# skills that use `../<file>` relative refs keep resolving after install.
+sync_shared_refs() {
+  local f
+  for f in _platform-mapping.md; do
+    if [ -f "$PARKED/$f" ] && [ ! -f "$ACTIVE/$f" ]; then
+      cp "$PARKED/$f" "$ACTIVE/$f"
+    fi
+  done
+}
+
 # enable one skill by folder name
 cmd_enable() {
   require_dirs
@@ -63,6 +74,7 @@ cmd_enable() {
   [ -d "$src" ] || { echo "not parked: $name" >&2; exit 1; }
   [ -d "$dst" ] && { echo "already active: $name"; exit 0; }
   cp -r "$src" "$dst"
+  sync_shared_refs
   echo "enabled: $name"
 }